You are on page 1of 422

11i Oracle HRMS

Technical Foundation
Human Resources

y
l
n

Student Guide Volume 2

O
e

I
A

&
l
a

n
r
te

14817GC10

n
I
e

Edition 1.0
January 2002

l
c
a

D34307

r
O

s
U

Copyright Oracle Corporation, 2002. All rights reserved.


This 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
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 for commercial computer software and shall be deemed
to be Restricted Rights software under Federal law, as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in
Technical Data and Computer Software (October 1988).
This material or any portion of it may not be copied in any form or by any means without the express prior written permission of the
Education Products group of Oracle Corporation. Any other copying is a violation of copyright law and may result in civil and/or
criminal penalties.
If this 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 in writing to Worldwide Education Services, Oracle Corporation, 500 Oracle Parkway, Box SB-6, Redwood Shores, CA 94065.
Oracle Corporation does not warrant that this document is error-free.
Oracle and all references to Oracle Products 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.

Author
Jeanne Cecil

y
l
n

Technical Contributors and Reviewers

Peter Attwood, Matthew Blowers, John Cafolla, Alison Chambers, Bob Eagles, Dave Kerr,
Ratna Kuplish, Carol Margolis, Andy McGhee, Jan Pierce, Sam Smith, Nancy Snider, John
Thuringer
This book was published using: oracle

tutor

&
l
a

n
r
te

r
O

l
c
a

n
I
e

I
A

s
U

O
e

Table of Contents
HRMS Architecture ..............................................................................................................1-1
11i Oracle HRMS: Technical Foundation ...........................................................................1-2
Objectives ............................................................................................................................1-3
Agenda.................................................................................................................................1-4
HRMS Architecture.............................................................................................................1-5
Objectives ............................................................................................................................1-6
Agenda.................................................................................................................................1-7
HRMS Architecture: Core HRMS.......................................................................................1-8
Objectives ............................................................................................................................1-9
Agenda.................................................................................................................................1-10
HRMS Products...................................................................................................................1-11
Objectives ............................................................................................................................1-12
Agenda.................................................................................................................................1-13
Oracle ERP Applications Functional View .........................................................................1-14
Application Architecture .....................................................................................................1-15
Application Tier...................................................................................................................1-16
Forms Client Applet ............................................................................................................1-17
Forms Network Traffic ........................................................................................................1-18
Oracle Applications .............................................................................................................1-19
Oracle Applications Database Objects ................................................................................1-21
Application Servers .............................................................................................................1-22
APPS Schema ......................................................................................................................1-24
Additional Schemas.............................................................................................................1-25
Multiple Organizations Views.............................................................................................1-26
Application Server Architecture ..........................................................................................1-27
APPL_TOP..........................................................................................................................1-28
APPL_TOP SubDirectories .................................................................................................1-29
Typical Product Directory ...................................................................................................1-31
File Types ............................................................................................................................1-33
Application Components and Architecture..........................................................................1-34
HRMS Product Family ........................................................................................................1-35
HRMS Suite.........................................................................................................................1-36
Information Driven Applications.........................................................................................1-38
HRMS Application Information ..........................................................................................1-39
Localizations........................................................................................................................1-41
Summary..............................................................................................................................1-42
HRMS Naming Conventions...............................................................................................1-43
Objectives ............................................................................................................................1-44
Agenda.................................................................................................................................1-45
Standards .............................................................................................................................1-46
HRMS Product Codes .........................................................................................................1-47
Legislation Codes ................................................................................................................1-48
Example Legislation Codes .................................................................................................1-49
Functional Areas: Examples ................................................................................................1-50
Object Naming Standards: Tables .......................................................................................1-51
Practice: Locate Objects ......................................................................................................1-56
Object Naming Standards: Views........................................................................................1-57
Object Naming Standards: Sequences and Constraints .......................................................1-60
Database Trigger Naming Standards ...................................................................................1-61
Practice: Identify Table Triggers .........................................................................................1-62
HRMS Functional Area Names ...........................................................................................1-63
Euro: Shadow Tables...........................................................................................................1-64

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


i

Symbolic Abbreviations ......................................................................................................1-65


Names ..................................................................................................................................1-66
Database Schema Architecture ............................................................................................1-68
Summary..............................................................................................................................1-69
Security Model ....................................................................................................................1-70
Objectives ............................................................................................................................1-71
Agenda.................................................................................................................................1-72
Security: Applications .........................................................................................................1-73
What are HRMS Security Needs? .......................................................................................1-75
Security at the Business Level.............................................................................................1-76
HRMS Security Components ..............................................................................................1-77
Unrestricted Access .............................................................................................................1-78
Security Groups New in 11i ................................................................................................1-79
Security Components: Secure Tables ..................................................................................1-80
Security Components: Lists and Views ...............................................................................1-81
Security Components: Security Profile................................................................................1-82
Security Profiles in SSHR ...................................................................................................1-83
Security Profiles in HRMS ..................................................................................................1-84
User Profiles ........................................................................................................................1-86
Security Components: Profiles ............................................................................................1-87
Profile Option: Cross Business Groups ...............................................................................1-88
Assign Responsibility to User .............................................................................................1-89
Processes and Owners .........................................................................................................1-90
View All Security Profile ....................................................................................................1-91
Security Profile Options ......................................................................................................1-92
R11i Security Profile Options..............................................................................................1-93
HR Security Profiles: Entire Picture....................................................................................1-94
HR Security Profiles............................................................................................................1-96
Other Users..........................................................................................................................1-101
Custom Tables .....................................................................................................................1-102
Summary..............................................................................................................................1-103
DateTrack ............................................................................................................................1-104
Objectives ............................................................................................................................1-105
Agenda.................................................................................................................................1-106
Datetracked or Dated Entities ..............................................................................................1-107
What Difference Does it Make? ..........................................................................................1-108
DateTrack in Forms .............................................................................................................1-110
Table Standards ...................................................................................................................1-111
Child Tables.........................................................................................................................1-114
Datetracked Views...............................................................................................................1-115
Practice: Enter and Change Employee Data ........................................................................1-116
Discussion Point ..................................................................................................................1-117
Comment Text .....................................................................................................................1-118
Views...................................................................................................................................1-119
DateTrack Mode Categories ................................................................................................1-120
Time Diagrams ....................................................................................................................1-121
Insert Mode..........................................................................................................................1-122
Update Modes......................................................................................................................1-123
Update Mode: CORRECTION............................................................................................1-124
Demo: Enter and Update Employee Data............................................................................1-125
Update Mode: UPDATE .....................................................................................................1-126
Update Mode: UPDATE_OVERRIDE ...............................................................................1-127
Update Mode: UPDATE_CHANGE_INSERT ...................................................................1-128
Delete Modes.......................................................................................................................1-129
Delete Mode: PURGE .........................................................................................................1-130
Delete Mode: Delete............................................................................................................1-131
Delete Mode: FUTURE_CHANGE ....................................................................................1-132

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


ii

Delete Mode: DELETE_NEXT_CHANGE ........................................................................1-133


DateTrack Rules and Functionality .....................................................................................1-135
Controlling DateTrack.........................................................................................................1-136
Practice: DateTrack Profile Options ....................................................................................1-138
Effective Date in Forms.......................................................................................................1-139
DateTrack HRMS Rules ......................................................................................................1-140
DateTrack Behind the Form ................................................................................................1-141
DateTrack History ...............................................................................................................1-142
Creating or Modifying a Datetracked View.........................................................................1-144
Summary..............................................................................................................................1-145
HRMS (Human Resources Management System Intelligence) ...........................................1-146
Objectives ............................................................................................................................1-147
Agenda.................................................................................................................................1-148
HRMSi - What is it? ............................................................................................................1-149
HRMSi Intended Users.....................................................................................................1-150
HRMSi Main Components ..................................................................................................1-151
Reporting Areas...................................................................................................................1-152
E-Business Intelligence Product Features............................................................................1-153
HRMSi Architecture............................................................................................................1-154
HRMSi Demo......................................................................................................................1-155
Discoverer Viewer:..............................................................................................................1-156
Discoverer Architecture.......................................................................................................1-157
OLTP Relational to Star Schema........................................................................................1-158
Setup: HRMS Intelligence Reports......................................................................................1-159
Performance Management Framework - Overview............................................................1-161
Business Views....................................................................................................................1-162
Logical Data Models and Business Views ..........................................................................1-163
Refreshing the EUL .............................................................................................................1-164
Setup Check List..................................................................................................................1-165
HRMS Intelligence Reports.................................................................................................1-166
Organizational Security .......................................................................................................1-168
HRMSi Summary ................................................................................................................1-169
Summary..............................................................................................................................1-170
HRMS Integration with Oracle Applications ......................................................................1-171
Objectives ............................................................................................................................1-172
Agenda.................................................................................................................................1-173
Oracle ERP Applications.....................................................................................................1-174
Application Foundations......................................................................................................1-175
Application Server Architecture ..........................................................................................1-176
Discussion Point ..................................................................................................................1-177
HRMS Suite.........................................................................................................................1-178
Global ERP Integration .......................................................................................................1-180
Terminology ........................................................................................................................1-181
Key Shared Entities .............................................................................................................1-182
Discussion Points.................................................................................................................1-188
Costing Details ....................................................................................................................1-189
Practice: Locate Views ........................................................................................................1-191
Comparison of Shared and Full HRMS Installations...........................................................1-192
HR Foundation Responsibility ............................................................................................1-194
Shared Forms and Windows................................................................................................1-195
Use of HRMS by other Oracle Applications .......................................................................1-197
HR Foundation: API Limits.................................................................................................1-200
Discussion Point ..................................................................................................................1-201
Integration Considerations...................................................................................................1-202
Summary..............................................................................................................................1-203

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Data and Processes ................................................................................................................2-1


Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


iii

HRMS Architecture: Data and Processes ............................................................................2-2


Objectives ............................................................................................................................2-3
Agenda.................................................................................................................................2-4
HRMS Data and Processes ..................................................................................................2-5
Objectives ............................................................................................................................2-6
Agenda.................................................................................................................................2-7
Person Data..........................................................................................................................2-8
Objectives ............................................................................................................................2-9
Agenda.................................................................................................................................2-10
Basic HRMS Data ...............................................................................................................2-11
Practice: Enter Minimum Person Data ................................................................................2-12
Application Tool: Examine Person_ID................................................................................2-13
Person Data..........................................................................................................................2-14
Person Types .......................................................................................................................2-15
Practice: Employee and Address Data.................................................................................2-16
Table Constraints.................................................................................................................2-17
Person Relations ..................................................................................................................2-18
Practice: Enter a Contact .....................................................................................................2-19
Person Relations ..................................................................................................................2-20
Summary..............................................................................................................................2-21
Data in HRMS Processes.....................................................................................................2-22
Objectives ............................................................................................................................2-23
Agenda.................................................................................................................................2-24
Practice: HRMS People Data...............................................................................................2-25
Employee Tables .................................................................................................................2-26
Assignment Status and Type ...............................................................................................2-27
Assignment Constraints.......................................................................................................2-29
Assignment Relations ..........................................................................................................2-30
Practice: HRMS People Data...............................................................................................2-31
Hire to Pay...........................................................................................................................2-32
Terminate Employment .......................................................................................................2-33
Practice: View Employee Start Date ...................................................................................2-34
Multiple Periods of Service .................................................................................................2-35
Terminate Employment Summary.......................................................................................2-36
Assignment Relations ..........................................................................................................2-37
Pay Details...........................................................................................................................2-39
Practice: Locate Salary ........................................................................................................2-40
Lookups ...............................................................................................................................2-41
Practice: Create a Flexfield Lookup ....................................................................................2-43
Summary..............................................................................................................................2-44
Basic HRMS FlexFields ......................................................................................................2-45
Objectives ............................................................................................................................2-46
Agenda.................................................................................................................................2-47
Flexfields .............................................................................................................................2-48
Key Flexfields .....................................................................................................................2-49
Protected Flexfields .............................................................................................................2-53
Personal Analysis Key Flex (Special Information Type) ....................................................2-54
Descriptive Flexfields..........................................................................................................2-55
DFF Security .......................................................................................................................2-56
Diagnostic Tools: Flexfields................................................................................................2-57
Summary..............................................................................................................................2-58
Information Types for Extending Data................................................................................2-59
Objectives ............................................................................................................................2-60
Agenda.................................................................................................................................2-61
SIT Special Information Types.........................................................................................2-62
SIT - Folders........................................................................................................................2-63
SIT Availability ................................................................................................................2-64

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


iv

Extra Information Type Flexfields ......................................................................................2-65


EIT Components..................................................................................................................2-66
EIT Location.....................................................................................................................2-67
EIT - Organization...............................................................................................................2-68
EIT - Job ..............................................................................................................................2-69
EIT - Position ......................................................................................................................2-70
EIT - Person.........................................................................................................................2-71
EIT Assignment................................................................................................................2-72
EIT contrasted with SIT ......................................................................................................2-73
Practice: Configure Extra Information ................................................................................2-74
Comprehensive Solutions ....................................................................................................2-75
Folders .................................................................................................................................2-76
Other Options ......................................................................................................................2-77
Summary..............................................................................................................................2-78
Reference Information.........................................................................................................2-80
Reference: Basic Applications Tools...................................................................................2-81
Reference Information.........................................................................................................2-82
Reference: Basic Applications Tools...................................................................................2-84
Reference: Drawing Attributes in ERDs .............................................................................2-85
Reference: Drawing Relationships in ERDs........................................................................2-86
Reference: Perspectives of Relationships in ERDs..............................................................2-87
Reference: Oracle Applications ERD Standards .................................................................2-88
Reference: HELP >..............................................................................................................2-92
Reference: HELP > Trace....................................................................................................2-93
Reference: PYUPIP .............................................................................................................2-94
Performance Topics...............................................................................................................3-1
Performance Topics.............................................................................................................3-2
Objectives ............................................................................................................................3-3
Agenda.................................................................................................................................3-4
Diagnosing Performance Issues...........................................................................................3-5
User Access .........................................................................................................................3-7
Optimizer Options: Rules and Cost .....................................................................................3-8
CBO in R11i ........................................................................................................................3-9
CBO Analyze.......................................................................................................................3-10
References ...........................................................................................................................3-13
Summary..............................................................................................................................3-14

O
e

y
l
n

I
A

s
U

Globalization ..........................................................................................................................4-1
Globalization .......................................................................................................................4-2
Objectives ............................................................................................................................4-3
Agenda.................................................................................................................................4-4
Language Support................................................................................................................4-5
Objectives ............................................................................................................................4-6
Agenda.................................................................................................................................4-7
Languages and Localizations...............................................................................................4-8
Language and Currency Relations.......................................................................................4-10
Localizations........................................................................................................................4-11
A Global Character Set........................................................................................................4-12
Multilingual Table Structure................................................................................................4-13
External Documents ............................................................................................................4-17
The General Preferences Page .............................................................................................4-18
Language Choices................................................................................................................4-19
Translated Navigator ...........................................................................................................4-20
Translated Form...................................................................................................................4-21
Date Format Choices ...........................................................................................................4-22
Date Format .........................................................................................................................4-23
Number Format Choices......................................................................................................4-24

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


v

Reference Data ....................................................................................................................4-25


Localizations........................................................................................................................4-28
Global Conversions .............................................................................................................4-29
Summary..............................................................................................................................4-30
Profile Options in Global Implementations .........................................................................4-31
Objectives ............................................................................................................................4-32
Agenda.................................................................................................................................4-33
Data Partitions .....................................................................................................................4-34
Information crossing Business Groups ................................................................................4-35
One or Multiple Business Groups........................................................................................4-36
Business Groups ..................................................................................................................4-38
Cross Business Group..........................................................................................................4-39
R11i Profile Option Decision Tree ......................................................................................4-40
Summary..............................................................................................................................4-41
Currency ..............................................................................................................................4-42
Objectives ............................................................................................................................4-43
Agenda.................................................................................................................................4-44
Business Group and Currency .............................................................................................4-45
Oracle Payroll and Currency ...............................................................................................4-46
Euro: Important Dates .........................................................................................................4-48
Euro as Functional Currency ...............................................................................................4-49
Euro as a Functional Currency ............................................................................................4-50
EFC Business Group Processing .........................................................................................4-51
EFC Process and Features ...................................................................................................4-52
EFC Planning.......................................................................................................................4-53
Actual Conversion ...............................................................................................................4-54
Conversion Concepts...........................................................................................................4-55
Conversion Steps .................................................................................................................4-56
Conversion Tasks ................................................................................................................4-58
EFC Conversion ..................................................................................................................4-59
Conversion: Preparation and Install.....................................................................................4-60
Conversion: Business Group cycle ......................................................................................4-61
Conversion: Validation........................................................................................................4-62
Conversion: Process ............................................................................................................4-63
Update Step .........................................................................................................................4-64
NCUs after Conversion .......................................................................................................4-65
Summary..............................................................................................................................4-66

O
e

y
l
n

I
A

s
U

Architecture Demonstrations and Practices........................................................................5-1


[HRMS Architecture] - Practice Details and Solutions .......................................................5-2
Practice: Identifying HRMS Objects ...................................................................................5-3
Solution: Identifying HRMS Objects ..................................................................................5-4
Demo and Practice: Viewing Datetracked Data ..................................................................5-6
Solution: Viewing Datetracked Employee Data ..................................................................5-7
Demo and Practice: DateTrack Modes ................................................................................5-11
Demo Solution: Viewing Datetracked Employee Data .......................................................5-12
Demo and Practice: DateTrack Profile Options...................................................................5-19
Practice Solution: DateTrack Profile Options......................................................................5-20
Demo: eBI HRMSi ...........................................................................................................5-21
Demonstration Solution: eBI HRMSi Workforce.............................................................5-22
Demo and Practice: Locate and Examine Views .................................................................5-23
Practice Solution: Locate and Examine Views....................................................................5-24

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Data and Processes Demos and Practices ............................................................................6-1


Instructor Demo and Practice: Enter Minimum Person Data...............................................6-2
Demo and Practice Solution: Enter Minimum Person Data ................................................6-3
Practice: Employee and Address .........................................................................................6-4
Practice Solution: Employee and Address...........................................................................6-5
Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


vi

Practice: Enter Contact ........................................................................................................6-6


Solution: Enter Contact .......................................................................................................6-7
Demo and Practice: Applicant, Employee, and Ex-Employee Data ...............6-7
Solution: Applicant, Employee, and Ex-Employee Data.....................................................6-9
Demo and Practice: View Employee Start Date ..................................................................6-12
Solution: View Employee Start Date...................................................................................6-13
Demo and Practice: Locate Salary Information...................................................................6-14
Practice Solution: Locate Salary Information......................................................................6-15
Practice: Lookups in HRMS................................................................................................6-18
Solution: Lookups in HRMS - HR_LOOKUPS View ........................................................6-19
Solution: View with Lookup ...............................................................................................6-20
Demo and Practice: Create Lookup .....................................................................................6-21
Solution: Create a Flexfield Lookup....................................................................................6-22
Practice: Configure Extra Information ................................................................................6-23
Solution: Configure Extra Information................................................................................6-24
APIs and Data Pump.............................................................................................................7-1
11i Oracle HRMS Interfaces ...............................................................................................7-2
Objectives ............................................................................................................................7-3
Agenda.................................................................................................................................7-4
APIs and Data Pump in HRMS ...........................................................................................7-5
Objectives ............................................................................................................................7-6
Business Process Approach APIs (Application Program Interfaces) ..................................7-7
Objectives ............................................................................................................................7-8
Agenda.................................................................................................................................7-9
Business Processes and APIs...............................................................................................7-10
Business Process Approach .................................................................................................7-11
HRMS Public APIs..............................................................................................................7-12
APIs Centralize Logic .........................................................................................................7-14
Using APIs...........................................................................................................................7-15
Module Structure .................................................................................................................7-16
Using APIs: Common Parameters .......................................................................................7-18
p_validate Parameter ...........................................................................................................7-19
p_language_code Parameter ................................................................................................7-21
Object Version Number (OVN)...........................................................................................7-22
OVN Locking Example .......................................................................................................7-24
Using APIs: Unique Parameters ..........................................................................................7-25
API Layers...........................................................................................................................7-26
API Layers Example............................................................................................................7-27
API Usage: Options and Guidelines ....................................................................................7-28
Web Browser and API to Insert Data ..................................................................................7-29
Practice: Calling HRMS APIs .............................................................................................7-31
Additional API Reference Information................................................................................7-32
Summary..............................................................................................................................7-34
HRMS Data Pump ...............................................................................................................7-35
Objectives ............................................................................................................................7-36
Agenda.................................................................................................................................7-37
Data Pump ...........................................................................................................................7-38
Advantages of Data Pump ...................................................................................................7-39
Components of the Data Pump ............................................................................................7-40
Data Pump Components ......................................................................................................7-41
The Meta Mapper ................................................................................................................7-42
Data Pump Interface Tables.................................................................................................7-43
Data Pump User Key Table .................................................................................................7-44
Data Pump Tables................................................................................................................7-46
Data Pump Views ................................................................................................................7-48
Generated PL/SQL Interfaces..............................................................................................7-49

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


vii

Data Pump Process Utilities ................................................................................................7-50


Data Pump Engine ...............................................................................................................7-51
Logging Options ..................................................................................................................7-52
Running PYUPIP.................................................................................................................7-53
Data Pump Key Features .....................................................................................................7-54
Data Pump Loading Tips .....................................................................................................7-55
Data Loading Data Flow......................................................................................................7-56
Practice: Loading Data Using Data Pump ...........................................................................7-57
Summary..............................................................................................................................7-58
Interface Tools and Utilities..................................................................................................8-1
Interface Tools and Utilities ................................................................................................8-2
Objectives ............................................................................................................................8-3
Agenda.................................................................................................................................8-4
BEE: Batch Element Entry ..................................................................................................8-5
Objectives ............................................................................................................................8-6
Agenda.................................................................................................................................8-7
BEE: Batch Element Entry ..................................................................................................8-8
Batch Element Entry Tables ................................................................................................8-10
BEE: PAY_BATCH_HEADERS........................................................................................8-11
BEE: PAY_BATCH_LINES...............................................................................................8-12
Additional Batch Validation ................................................................................................8-13
Practice: Using BEE in SQL*Plus.......................................................................................8-15
Summary..............................................................................................................................8-16
System Data Extract ............................................................................................................8-17
Objectives ............................................................................................................................8-18
Agenda.................................................................................................................................8-19
Benefit System Data Extract................................................................................................8-20
Extract Definition: ...............................................................................................................8-22
Extract Levels......................................................................................................................8-23
Summary..............................................................................................................................8-26
Data Loaders and Updates ...................................................................................................8-27
Objectives ............................................................................................................................8-28
Agenda.................................................................................................................................8-29
Data Loaders........................................................................................................................8-30
ATG Dataextract/Datamerge ...............................................................................................8-31
ATG Data Loaders and APIs...............................................................................................8-33
HR Data Uploader ...............................................................................................................8-35
HRDU (HR Data Uploader) ................................................................................................8-36
SQL .....................................................................................................................................8-37
Mass Updates.......................................................................................................................8-38
Summary..............................................................................................................................8-39
Interface Direction...............................................................................................................8-40
Objectives ............................................................................................................................8-41
Agenda.................................................................................................................................8-42
Interface Builders ................................................................................................................8-43
HR Development Interface Model.......................................................................................8-44
Interface Types ....................................................................................................................8-45
Vendor-Specific Interfaces ..................................................................................................8-47
Summary..............................................................................................................................8-48
Generic Payroll Interface Kit...............................................................................................8-49
Objectives ............................................................................................................................8-50
Agenda.................................................................................................................................8-51
Payroll Interfaces.................................................................................................................8-52
Overview of Toolkit ............................................................................................................8-53
Payroll Interface Toolkit......................................................................................................8-54
Data Flow ............................................................................................................................8-55

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


viii

Overview of Data Flow .......................................................................................................8-56


Backfeed ..............................................................................................................................8-57
HR Setup Considerations.....................................................................................................8-59
Setup Restrictions ................................................................................................................8-61
Interface Views....................................................................................................................8-62
Backfeed APIs .....................................................................................................................8-64
Features for Configuring .....................................................................................................8-65
Triggers and Legislative Areas ............................................................................................8-66
Dynamic Triggers ................................................................................................................8-67
HR Development Interface Model.......................................................................................8-68
Summary..............................................................................................................................8-69
ADE (Application Data Exchange) ......................................................................................9-1
ADE (Application Data Exchange) .....................................................................................9-2
Objectives ............................................................................................................................9-3
Agenda.................................................................................................................................9-4
The ADE Product ................................................................................................................9-5
Process Overview ................................................................................................................9-6
Applications Mode ..............................................................................................................9-8
Implementation and Environment .......................................................................................9-9
ADE in 10.7sc .....................................................................................................................9-10
ADE in NCA .......................................................................................................................9-11
ADE in R11+ Environment .................................................................................................9-13
Access ADE from the Applications.....................................................................................9-14
ADE Components................................................................................................................9-15
ADE Modes .........................................................................................................................9-16
Installing ADE - Prerequisites .............................................................................................9-18
Basic ADE Setup Steps .......................................................................................................9-19
ADE Installation Process.....................................................................................................9-20
Define Options.....................................................................................................................9-21
System Administration Options...........................................................................................9-22
Identify Tools ......................................................................................................................9-23
HRIO Functions in Menu ....................................................................................................9-24
Setup Checklist....................................................................................................................9-26
Setup Checklist Letter Generation....................................................................................9-27
Key ADE Files ....................................................................................................................9-28
Using ADE ..........................................................................................................................9-29
ADE Security.......................................................................................................................9-30
Manage Styles .....................................................................................................................9-31
ADE Styles ..........................................................................................................................9-32
Create Styles........................................................................................................................9-33
ADE Queries .......................................................................................................................9-35
Define Query .......................................................................................................................9-36
Querying Data .....................................................................................................................9-37
Launching ADE Standalone ................................................................................................9-38
ADE from Application Mode ..............................................................................................9-40
ADE Uploads: Modify Data ................................................................................................9-41
Letter Request Mode ...........................................................................................................9-43
Letter Request Setup............................................................................................................9-44
Using ADE - ADE.ini file ...................................................................................................9-46
Using ADE - Menu Functions .............................................................................................9-48
Troubleshooting ADE..........................................................................................................9-49
Troubleshooting: Installation Problems..............................................................................9-50
Troubleshooting: Application Problems ..............................................................................9-51
Troubleshooting: Behavior Problems ..................................................................................9-52
Troubleshooting Tools.........................................................................................................9-53
Practice: Using ADE Features .............................................................................................9-55

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


ix

Summary..............................................................................................................................9-56
HRMS Interfaces: APIs and Data Pump Demos and Practices ........................................10-1
Practice: Calling HRMS Business Process APIs .................................................................10-2
Instructor Demonstration Solution: Locating HRMS API code ..........................................10-3
Practice: Calling an HRMS API ..........................................................................................10-5
Calling an API: Practice Solution........................................................................................10-6
Practice: Data Pump ............................................................................................................10-11
Practice Solution: Data Pump..............................................................................................10-12
HRMS Interfaces: Tools and Utilities Demos and Practices..............................................11-1
Practice: Batch Element Entry API .....................................................................................11-2
Practice Solution: Batch Element Entry API .......................................................................11-3
HRMS Interfaces: ADE Demos and Practices ....................................................................12-1
Practice: ADE Styles and Upload Modes ............................................................................12-2
Solution: ADE Styles...........................................................................................................12-3
Solution: Using ADE Upload ..............................................................................................12-4
Extending Business Rules in HRMS ....................................................................................13-1
11i Oracle HRMS: Extending Business Rules in HRMS ....................................................13-2
Objectives ............................................................................................................................13-3
Agenda.................................................................................................................................13-4
Extensions and Restrictions.................................................................................................13-6
Objectives ............................................................................................................................13-7
Agenda.................................................................................................................................13-8
Business Rule Framework ...................................................................................................13-9
API Layers and Triggers......................................................................................................13-10
Survey of Delivered Extensions ..........................................................................................13-12
Configuration Options .........................................................................................................13-15
Summary..............................................................................................................................13-16
Custom Library....................................................................................................................13-17
Objectives ............................................................................................................................13-18
Agenda.................................................................................................................................13-19
What Is Custom Library? ....................................................................................................13-20
Custom Library Architecture...............................................................................................13-21
Custom Library Structure ....................................................................................................13-22
Uses of the Custom Library.................................................................................................13-23
Zooms: Jump to Form..........................................................................................................13-24
Zoom: Enable Zoom............................................................................................................13-25
Zoom: Call New Form.........................................................................................................13-26
Generic Event Points ...........................................................................................................13-27
'Event' Code Structure .........................................................................................................13-28
Product Specific Events.......................................................................................................13-29
Custom Library Uses ...........................................................................................................13-31
Example 1: Highlight Fields................................................................................................13-32
Example 2: Remove Field(s) ...............................................................................................13-34
Example 3: Override LOV...................................................................................................13-36
Example 4: Override Default Where Clause .......................................................................13-38
Example 5: Call Server Side Procedure...............................................................................13-40
Example 6: Defaulting Field Values....................................................................................13-42
Design Considerations.........................................................................................................13-43
Date Track Considerations ..................................................................................................13-44
Code Considerations............................................................................................................13-45
Suggested Business Rule Framework..................................................................................13-47
Fundamentals.......................................................................................................................13-48
Practice: Custom Library.....................................................................................................13-49
Summary..............................................................................................................................13-50
API User Hooks...................................................................................................................13-51

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


x

Objectives ............................................................................................................................13-52
Agenda.................................................................................................................................13-53
User Hook Overview ...........................................................................................................13-54
Hook Code Relationship......................................................................................................13-56
Uses of Hooks......................................................................................................................13-57
Implementing: Overview .....................................................................................................13-58
Implementing User Hooks...................................................................................................13-59
Available User Hooks..........................................................................................................13-60
Available Data .....................................................................................................................13-64
Implementing Extra Logic...................................................................................................13-65
Register Extra Logic............................................................................................................13-67
Error Handling and Messages..............................................................................................13-69
User Hooks in the Business Rule Framework .....................................................................13-70
Practice: User Hook Validation ...........................................................................................13-71
Summary..............................................................................................................................13-72
FastFormula Extensions: Database Items ............................................................................13-73
Objectives ............................................................................................................................13-74
Agenda.................................................................................................................................13-75
Overview .............................................................................................................................13-76
Database Items and FastFormula.........................................................................................13-77
Database Item Advantages ..................................................................................................13-78
Database Items: Application Dictionary..............................................................................13-79
Components of Database Items ...........................................................................................13-80
Database Items in FF_ tables...............................................................................................13-82
Database Item Contexts .......................................................................................................13-83
Designing the Database Item ...............................................................................................13-84
Building the Database Item .................................................................................................13-85
Using the Database Item......................................................................................................13-87
Database Items - Troubleshooting .......................................................................................13-88
Practice: Database Item Components ..................................................................................13-89
Summary..............................................................................................................................13-90
FastFormula Custom Functions...........................................................................................13-91
Objectives ............................................................................................................................13-92
Agenda.................................................................................................................................13-93
FastFormula Functions ........................................................................................................13-94
Components of a FastFormula Function..............................................................................13-95
FastFormula in HRMS.........................................................................................................13-96
Delivered Formula Functions ..............................................................................................13-97
Business Requirements........................................................................................................13-98
Custom Functions ................................................................................................................13-99
Design and Limitations........................................................................................................13-100
Setup Formula Functions.....................................................................................................13-101
Practice: Creating a Function...............................................................................................13-102
Summary..............................................................................................................................13-103
Calling Formulas from PL/SQL ..........................................................................................13-104
Objectives ............................................................................................................................13-105
Agenda.................................................................................................................................13-106
Business Requirements for Formulas ..................................................................................13-107
Formulas in Business Rule Framework ...............................................................................13-108
Execution Engine.................................................................................................................13-109
Overall Process ....................................................................................................................13-110
Engine Processes .................................................................................................................13-114
Design Considerations.........................................................................................................13-115
Summary..............................................................................................................................13-118
Forms Configurator .............................................................................................................13-119
Objectives ............................................................................................................................13-120
Agenda.................................................................................................................................13-121

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xi

Forms Configurator .............................................................................................................13-122


Template Administration .....................................................................................................13-124
Using Templates ..................................................................................................................13-125
Template Windows..............................................................................................................13-126
Template Features................................................................................................................13-127
Using the Templates ............................................................................................................13-130
Practice: Configuring a Template ........................................................................................13-131
Summary..............................................................................................................................13-132
Extending Security ................................................................................................................14-1
Extending Security ..............................................................................................................14-2
Objectives ............................................................................................................................14-3
Agenda.................................................................................................................................14-4
Review: HRMS Security Components ................................................................................14-5
Restricted by Row and Column ...........................................................................................14-6
Security Components: Lists and Views ...............................................................................14-7
Security Profile ....................................................................................................................14-8
HR Security Profiles............................................................................................................14-10
Extending Security ..............................................................................................................14-11
Practice: Custom Security Profiles ......................................................................................14-12
Summary..............................................................................................................................14-13
Business Rule Extensions Demos and Practices ..................................................................15-1
Extending Business Rules in HRMS Demos and Practices.................................................15-2
Practice: Custom Library.....................................................................................................15-3
Custom Library Solution .....................................................................................................15-4
Instructor Demo and Practice: User Hook Validation .........................................................15-14
Instructor Demo and Practice Solution: User Hook Validation...........................................15-15
Instructor Demo and Practice: Database Item Components ................................................15-19
Solution: Database Item Components..................................................................................15-20
Instructor Demonstration: Creating a Function ...................................................................15-25
Instructor Demonstration and Practice Solution ..................................................................15-26
Instructor Demonstration and Practice: Configuring a Template ........................................15-30
Solution: Configuring a Template .......................................................................................15-31

O
e

y
l
n

s
U

Extending Security Demo and Practice ...............................................................................16-1


Extending Security Demo and Practice ...............................................................................16-2
Instructor Demonstration and Practice Solution ..................................................................16-3
Instructor Demonstration: Custom Security Profile ............................................................16-5
Instructor Demonstration and Practice Solution ..................................................................16-6

I
A

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xii

Preface
Profile
Before You Begin This Course
Before you begin this course, you should have the following qualifications:

Working knowledge of Oracle HRMS implementation and end-user tasks

Working knowledge of SQL*Plus and PL/SQL

Working experience with Oracle Applications System Administration

Working experience with Oracle HRMS System Administration, including


Taskflows, Menus, and Responsibilities

Familiarity with Oracle Forms libraries is preferred but not required

Prerequisites

R11i Implementing Oracle HRMS, 14805GC10, ILT or legislative equivalent

R11i Oracle HRMS: Administering Oracle HRMS, 14590GC10, ILT

Introduction to Oracle SQL and PL/SQL, 41010GC13, ILT or equivalent

y
l
n

O
e

How This Course Is Organized

s
U

R11i Oracle HRMS Technical Foundation is an instructor-led course featuring lecture, instructor
demonstrations, and hands-on exercises. Online demonstrations and written practice sessions
reinforce the concepts and skills introduced.

I
A

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xiii

Related Publications
Oracle Publications
Title

Part Number

R11i Implementing Oracle HRMS

A7331301

R11i Oracle Applications System


Administrators Guide

A75396-04

Customizing, Reporting, and System


Administration in Oracle HRMS (US)

A7329601

Oracle eBusiness Suite / Electronic


Technical Reference Manual eTRM

(Metalink) Version 2.0

Additional Publications

Technical Essays in R11i Implementing Oracle HRMS

Installation and users guides

read.me files

White Papers available on Metalink

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xiv

Typographic Conventions
Typographic Conventions in Text
Convention
Bold italic

Element
Glossary term (if
there is a glossary)

Example
The algorithm inserts the new key.

Caps and
lowercase

Buttons,
check boxes,
triggers,
windows

Click the Executable button.


Select the Cant Delete Card check box.
Assign a When-Validate-Item trigger to the
ORD block.
Open the Master Schedule window.

Courier new,
case sensitive
(default is
lowercase)

Code output,
directory names,
filenames,
passwords,
pathnames,
URLs,
user input,
usernames

Code output: debug.set (I, 300);


Directory: bin (DOS), $FMHOME (UNIX)
Filename: Locate the init.ora file.
Password: User tiger as your password.
Pathname: Open c:\my_docs\projects
URL: Go to http://www.oracle.com
User input: Enter 300
Username: Log on as scott

Initial cap

Graphics labels
(unless the term is a
proper noun)

Customer address (but Oracle Payables)

Emphasized words
and phrases,
titles of books and
courses,
variables
Interface elements
with long names
that have only
initial caps;
lesson and chapter
titles in crossreferences

Do not save changes to the database.


For further information, see Oracle7 Server
SQL Language Reference Manual.
Enter user_id@us.oracle.com,
where user_id is the name of the user.
Select Include a reusable module component
and click Finish.

SQL column
names, commands,
functions, schemas,
table names

Use the SELECT command to view


information stored in the LAST_NAME
column of the EMP table.

Italic

Quotation
marks

O
e

I
A

&
l
a

s
U

This subject is covered in Unit II, Lesson 3,


Working with Objects.

n
r
te

Uppercase

r
O

l
c
a

n
I
e

y
l
n

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xv

Convention
Arrow
Brackets

Element
Menu paths
Key names

Example

Commas

Key sequences

Plus signs

Key combinations

Press and release keys one at a time:


[Alternate], [F], [D]
Press and hold these keys simultaneously:
[Ctrl]+[Alt]+[Del]

Select File> Save.


Press [Enter].

Typographic Conventions in Code


Convention
Caps and
lowercase
Lowercase

Element
Oracle Forms
triggers
Column names,
table names

Example
When-Validate-Item

Passwords

DROP USER scott


IDENTIFIED BY tiger;
OG_ACTIVATE_LAYER
(OG_GET_LAYER
(prod_pie_layer))

PL/SQL objects

SELECT last_name
FROM s_emp;

Lowercase
italic
Uppercase

Syntax variables

y
l
n

O
e

CREATE ROLE role

SQL commands and SELECT userid


FROM emp;
functions

I
A

Typographic Conventions in Navigation Paths

s
U

This course uses simplified navigation paths, such as the following example, to direct you
through Oracle Applications.
Example:

&
l
a

n
r
te

Assignment Window
(N) People > Enter and Maintain > (M) Query-Find > (B) Assignment
This simplified path translates to the following:
1 (N) From the Navigator, select People > Enter and Maintain.
2 (M) From the menu, select Query > Find your employee.
3 (B) Click the Assignment button.

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xvi

Notations :
(N) = Navigator
(M) = Menu
(T) = Tab
(I) = Icon
(H) = Hyperlink
(B) = Button
Typographical Conventions in Help System Paths
This course uses a navigation path convention to represent actions you perform to find
pertinent information in the Oracle Applications Help System.
The following help navigation path, for example
Oracle HRMS Global > Compensation and Benefits Setup > How To > Define Elements >
Define an Element

y
l
n

represents the following sequence of actions:

O
e

1. In the navigation frame of the help system window, expand the Oracle HRMS Global entry.
2. Under the Oracle HRMS Global entry, expand Compensation and Benefits Setup.
3. Under Compensation and Benefits Setup, select How To.
4. Under How To, select Define Elements
5. Under Define Elements, select Define an Element

&
l
a

I
A

s
U

This will display step by step instructions on how to complete the Element window.

n
r
te

Getting Help

n
I
e

Oracle Applications provides you with a complete online help facility.


Whenever you need assistance, simply choose an item from the Help menu to pinpoint the type
of information you want.

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xvii

To display help for a current window:


1.

Choose Window Help from the Help menu, click the Help button on the toolbar, or hold
down the Control key and type 'h'.
A web browser window appears, containing search and navigation frames on the left, and a
frame that displays help documents on the right.
The document frame provides information on the window containing the cursor. The
navigation frame displays the top-level topics for your responsibility, arranged in a tree
control.

2.

If the document frame contains a list of topics associated with the window, click on a topic
of interest to display more detailed information.

3.

You can navigate to other topics of interest in the help system, or choose Close from your
web browser's File menu to close help.

Searching for Help


You can perform a search to find the Oracle Applications help information you want. Simply
enter your query in the text field located in the top-left frame of the browser window when
viewing help, then click the adjacent Find button.

y
l
n

A list of titles, ranked by relevance and linked to the documents in question, is returned from
your search in the right-hand document frame. Click on whichever title seems to best answer
your needs to display the complete document in this frame. If the document doesn't fully answer
your questions, use your browser's Back button to return to the list of titles and try another.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

R11i, Oracle Human Resources: Technical Foundation Table of Contents


xviii

APIs and Data


Pump
Chapter 7

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 1

11i Oracle HRMS Interfaces

11i Oracle HRMS Interfaces

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 2

Objectives
Objectives
After completing this module, you should be able to do
the following:
Describe and use interfaces, including APIs
(Application Program Interfaces)
Identify HRMS interface tools
Describe ADE (Application Data Exchange)
capabilities and setup

1-2

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This module describes the business process approach of HRMS Development to
interfaces, which includes components behind and beyond the professional
interface (forms) for getting data into and out of HRMS. Functionality of APIs
(Application Program Interfaces or Application Programmatic Interfaces),
payroll interfaces, and ADE (Application Data Exchange) are introduced.
The components of this module can be used for:

converting legacy data into

integrating other applications into

interfacing other applications with


Oracle HRMS.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 3

Agenda
Agenda
APIs (Application Program Interfaces) and Data
Pump
Additional Interface Tools and Utilities
ADE (Application Data Exchange)

1-3

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 4

APIs and Data Pump in HRMS

APIs and Data Pump in HRMS

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 5

Objectives
Objectives
After completing this unit, you should be able to do
the following:
Describe and use APIs (Application Program
Interfaces)
Identify HRMS Data Pump tables and process
Discuss how Data Pump and APIs are related

1-5

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This unit describes the HRMS APIs and their use in Data Pump. APIs are the
primary building block for most interfaces.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 6

Business Process Approach APIs (Application Program


Interfaces)

Business Process Approach APIs


(Application Program Interfaces)

y
l
n

Copyright Oracle Corporation, 2001. All rights reserved.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 7

Objectives
Objectives
After completing this lesson, you should be able to do
the following:
Describe application development standards and
the use of APIs (Application Program Interfaces) in
HRMS
Identify public APIs and their parameters
Know how and why to use HRMS APIs

1-7

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This lesson introduces the HRMS business process approach and the strategy of
using APIs as the foundation for HRMS data. You will learn how to identify
publicly callable and supported APIs, specific parameters, and the guidelines
for using SQL scripts to call APIs. Other tools that help to automate interfaces
are also introduced.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 8

Agenda
Agenda

HRMS Business process approach


Publicly callable APIs
API Processing
API Parameters
Calling APIs

1-8

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 9

Business Processes and APIs


Business Processes and APIs
Data entry packaged into Business processes
Hire an Employee
Update an Assignment

Creates high-level process


Hides complexity of application tables
Allows validation extensions for business rules

1-9

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Business Processes and APIs


It is easy to think of primary HRMS employee transactions in terms of
processes. Having APIs which handle the layers of complexity for multiple
tables and sub-processes allows the technical implementor both to reuse APIs
with any preferred user-interface and to insert custom logic into specific points
of the API process.
For example, consider the API which creates an employee: the person type must
be validated, birth date may be validated against start date and hire date, a
record must be created in the period of service table. Additionally, default
assignment, payroll, other units are created or validated. Having one API that
manages all of these functions in one call simulates the actions taken when a
user enters person information through the forms.
Oracle HRMS provides APIs which you can call through user-written SQL
scripts or other utilities. This flexibility permits you to create or use alternate
data interfaces such as custom forms or a conversion process to
programmatically enter data into the HRMS tables. You do not need to
understand the relation of all tables and processes, but you need to know how to
identify the business process required, the publicly callable APIs, and the points
where extra code can be attached to APIs.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 10

Business Process Approach


Business Process Approach
Processes
Protecting HRMS Database Tables

1-10

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Business Process APIs in HRMS


As an example of the processes covered, the following list includes public
generic (not legislative-specific) APIs only for Employees and assignments;
additional APIs manage applicants and assignments.
- activate_emp_asg
- create_secondary_emp_asg
- suspend_emp_asg
- update_emp_asg
- update_emp_asg_criteria
- actual_termination_emp_asg
- final_process_emp_asg
- update_pds_details
- create_employee
- re_hire_ex_employee
- actual_termination_emp
- final_process_emp
- update_term_details_emp

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 11

HRMS Public APIs


HRMS Public APIs
Access of Delivered APIs
Features for Identifying Publicly callable APIs

1-11

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HRMS Public APIs


Each API is a PL/SQL package, which provides an open interface to the
database. HRMS APIs use parameters, providing a friendly layer for managing
data entry, allowing you to avoid the complexity of database table and business
rule restrictions.
Oracle HRMS contains many APIs, but only certain of the delivered APIs are
supported for customer use; these are the Publicly Callable APIs.
Publicly Callable APIs validate in the same manner as application forms, in
several directions: first, data integrity validates data relationships between
tables, and secondly, ensures that business functionality is validated to the same
effect that the application form enforces. For this reason, only publicly callable
APIs should be used for accessing HRMS tables.
Current information for identifying an API as public or published is
maintained in Online Help; you can access Online Help for APIs from within
the application at:
(Help) Oracle HRMS > Extend Oracle HRMS > Custom Library Events and
APIs >
Publicly Callable Business Process APIs

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 12

Historically, published APIs were identified internally by the following SQL


comments:
-- Access Status:
-- Public.
However, Online Help provides a current list; it is the recommended method of
identifying publicly callable and Supported APIs.
To locate APIs: core product API scripts are located in the product TOP
admin/sql directories. Refer to filenames such as *api.pkh; localization-specific
APIs follow a *LLi.pkh naming standard, where LL is the two letter localization
code. For example, the hr_employee_api package header can be found in the
$PER_TOP/admin/sql/peempapi.pkh file."
You can identify the package name of an API as compiled into the Oracle
database, the package name, and current version number by using SQL*Plus
and APPS access. Use the following Select to retrieve the header line of the
package and package body:
>SELECT text
FROM all_source
WHERE name like '%<API_NAME>%'
AND text like '%Header%';
You can also search files in the API directory, comparing versions of the API
package in your operating system directory and the one compiled in your
database. You can use the following Unix command or your operating system
equivalent:
prompt>strings -a packagename | grep Header

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 13

APIs Centralize Logic


APIs Centralize Logic
Application and Validation Logic into server
Single code source

Development methodology changes


User Interface easier to implement

1-12

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Centralized Logic
You can use the published APIs as an alternative data entry point into Oracle
HRMS. Instead of accessing data using the online forms, you can implement
other programs to perform similar operations.
These other programs do not modify data directly in the database. They call the
APIs which:
Ensure it is appropriate to allow that particular business and datetracked
operation
Validate the data passed to the API
Insert/update/delete data in the HRMS schema

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 14

Using APIs
Using APIs
Java

C Code
Web

Forms

APIs
Spreadsheets
Data Loading

3rd Party Interfaces

1-13

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Using APIs
The effect of API design in Oracle HRMS is an insulating layer between the
user and the data-entry mode, simplifying data-manipulation and protecting
customer extensions on upgrade. The APIs are executable PL/SQL package
procedures that use parameters and provide full data validation and
manipulation. This allows you to use delivered functionality with various
interfaces, including custom interfaces.
Layers allow you to extend logic at specific points in nested procedures (using
User Hooks, discussed separately). The APIs layer allows you to execute
business rules in the database not just in the form layer. This layer:
Supports the use of alternative interfaces to HRMS, such as web pages or
spreadsheets
Guarantees that all transactions comply with configured and delivered
business rules
Simplifies integration of Oracle HRMS with other systems or processes
Provides support for initial or staged data loading
Insulates your custom logic and scripts from changes in underlying tables
Simplifies managing upgrades by limiting changes to possible parameter
additions.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 15

Module Structure
Module Structure

Programs

APIs

Database

Database complexity hidden from end user !

1-14

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

API Structure
The work carried out by each API can be split into the following three parts.
1. Check that the Business Process is Appropriate
Oracle HRMS uses system person types for specific processes. For example, a
person who applies to join company is an applicant. When the applicant is
accepted, the person details change to become an employee. This change is
achieved by the hire applicant API. The API first confirms that the person is an
applicant.
2. Validate Data Provided
Validate against the organizations business rules. For example, when entering a
new employee, you may require that the user specifies the persons nationality.
If the nationality is entered incorrectly, an error is generated. The new employee
entry is therefore rejected.
3. Database Inserts/Updates/Deletes
If the data passes validation checks, the database is modified by an Insert,
Update, or Delete, depending on the API. It is important to note that data passed
through one API often causes changes in more than one table. Rule validation
crosses table boundaries.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 16

A sound knowledge of PL/SQL is required to create modified packages which


meet your localization and business process needs. You should never modify
delivered APIs; such modifications are not supported.
The source code for the APIs resides on the Applications server. You will find
them in the SQL subdirectory under the applications directory, for example,
$PER_TOP/admin/sql and $PER_TOP/patch/115/sql
Parameters
You can find the parameters for each API by looking at comments in the
package header creation scripts or by using SQL*Plus.
A list of the IN parameters and OUT parameters is contained in the package
header creation script documentation.
Database Integrity
APIs control processing and validation. Detected errors are raised just as any
other PL/SQL error in Oracle applications. When an error is raised, all the work
done by that single API call is rolled back. Since your script, not the API,
controls the commit action, there is no danger that partial work will be entered
in the database. Only the calling code issues commits.
No Query/Read Interfaces
APIs provide mechanism for insert, update, and delete but they do not provide
query/ read stored package procedures. You have to extract data at the server
using SQL statements, database tables, existing views, or other utilities and
tools.
Flexfield Support
Flexfield validation is supported in APIs; however, you need to be aware that
APIs imply restrictions to validation and Value Sets. For example, Value Sets
or validation that reference a form field are not allowed because the field value
is inaccessible to the API. For complete details and recommended solutions, see
the essay on Validation of Flexfield Values in the Release 11i Implementation
Guide (Technical Essays, chapter 9) also available through Metalink patch
960733. The possible problem areas in APIs and flexfield value set validation
are references to:
User profile options
Form block.field items
A row in the FND_SESSIONS database table
Problems may also be caused by:
Incomplete context field value lists
Using the segment separator in data

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 17

Using APIs: Common Parameters


Using APIs: Common Parameters
p_datetrack_<datetrack-action>_mode, such as
p_datetrack_update_mode

p_validate
p_language
p_object_version_number

1-15

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

API Common Parameters


APIs contain several processing control parameters that do not map to database
columns. A discussion of each parameter follows:
p_datetrack_
APIs contain several processing control parameters that do not map to database
columns.
The p_datetrack_mode parameter varies with API style (create, update, delete)
and the business rules for relations with other records. For example, when
available, the 'DELETE' p_datetrack_delete_mode will end date the record, but
the ZAP mode will remove it from the database. Parameters for datetracked
features follow the same rules as DateTrack option availability in forms.
Technical Note
Complete details and examples can be found in the APIs in Oracle HRMS
technical essay in the Implementing Oracle HRMS manual.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 18

p_validate Parameter
p_validate Parameter
A parameter that allows you to control the insert,
update, or delete action
Boolean values
TRUEvalidate only
FALSEvalidate and manipulate (default)

1-16

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

p_validate
This parameter allows you to control whether data is actually changed or only
validated against the data, business, and custom rules. You can call the API any
number of times with the value set to TRUE, to simply validate without entering
any changes in the HRMS tables. The default value is FALSE, which both
validates and manipulates data in the HRMS tables.
For example:
If you need to route an employees information, you can hold the data in a
temporary table and validate it each time changes are made, setting the value to
TRUE. When you are ready to commit the change, simply allow the parameter
p_validate to default to FALSE.
Another example is a custom form that allows various actions to accumulate or
repeatedly change values before the user commits. In that case you would want
to validate each time data in the form changed, but make the actual change only
if and when the user saves the changes (the form commits).
parameter validate?
Manipulate?
FALSE
validate
insert, update, delete
TRUE
validate
no action on table(s)

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 19

FALSE
When using Validate mode = FALSE: return values for any OUT, IN OUT, and
Warning parameters will be set by the process.
TRUE
A savepoint is issued at the start of an API call with p_validate = TRUE, and a
rollback is performed once the API has completed. The process only validates,
and does not manipulate table data.
If the procedure is successful:
non warning OUT parameters are set to null,
warning OUT parameters are set to a specific value, and
IN OUT parameters are set to their original IN values.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 20

p_language_code Parameter
p_language_code Parameter
Allows you to control language, used by APIs that
have
Create and update style
Multi-lingual support features

1-17

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

P_language_code
HRMS entities provide Multilingual Support (MLS), with translated values in
_TL tables. The same surrogate key ID column and value identify translated and
non translated values; the MLS API PL/SQL procedure call manages both sets
of values. The p_language_code parameter is available only on create and
update style MLS APIs; it allows you to specify the translation value language.
The parameter can refer to different base or installed languages to translate data
in the same database. If this parameter is null, the default value of
hr_api.userenv_lang refers to the default language, as in select
userenv(LANG) from dual.
Each call to an update MLS API can change the non-translated values and one
set of translated values. The API updates the non-translated values in the main
table and translated data on corresponding row(s) in the _TL table, inserting a
row into the _TL table for each base and installed language.
For further information, see the Oracle Applications Concepts Manual for
details on Principles of MLS, or the Oracle Applications Install Guide for
details on Configuration of MLS.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 21

Object Version Number (OVN)


Object Version Number (OVN)

OVN on DateTrack tables


Advantages of using OVN
Disadvantages of using OVN
Extra forms logic to support OVNs

1-18

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Object Version Number


Object Version Number (OVN) controls object locking in the database, using a
column called OBJECT_VERSION_NUMBER.
Update-style APIs use the OVN code: OVN is accessed during a query, tracking
any possible simultaneous updates.
When an attempt is made to save a transaction that updates data, the current
OVN in the table is compared with the OVN value being passed back from the
transaction. If the OVNs are equal, the transaction is saved and completed.
However, if the OVNs are no longer equal, the update is rejected and the user
must requery to make latest changes.
For Create APIs, the OVN is defined as an OUT parameter: the API assigns the
value 1 to OVN at row inserts. For Update APIs, the parameter is defined as IN
OUT and the OVN is mandatory: in your SQL API call, you can select the latest
OVN by using the maximum function on the object_version_number field.
Locking Methods
Locking at query time for existing records is very restrictive: it prevents other
users from altering the data until you release the lock.
A less restrictive method is used in Oracle Forms: locking when a row is
changed. You can query a row without taking out a lock. Forms compares
existing values against the database and if they are the same (no other user has
changed the record) the lock is made; otherwise, the message Record modified
by another user, requery displays. A lock is held when a record is modified;
the lock is released at commit or rollback.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 22

Problems with Lock when a row is changed


If this mode of locking is used within HRMS APIs, it is necessary to check all
old and new values to see if another user has already changed a row.
When a new row is inserted, the API normally sets the OVN attribute to 1. The
OVN attribute is incremented when a row is updated; it is never decremented or
set to a lower number.
However, the OVN is not unique and does not replace the primary key. There
can be many rows in the same table with the same OVN. The OVN indicates the
version of a specific primary key row.
How OVN Locking Works
When a database row is transferred to a client following a query, the current
OVN is also transferred. The current OVN is then compared with the OVN on
the database. If the OVN values are the same, the row on the server is in the
same state as when the attributes were transferred to the client, and the request
proceeds. If, however, the row is then modified and committed and by another
user, the OVN on the database is incremented. The OVN values are different
and the request is disallowed.
Database locks are still used to prevent uncommitted changes being overwritten
by another user.
OVN on DateTrack Tables
OVN operates on datetracked and non-datetracked tables in a similar manner:
each row of a primary key record has its own OVN. When a new OVN is
needed, it is calculated by adding one to the maximum OVN of all row
instances for the primary key value. This is logic similar to what you create for
API calls.
Advantages of OVN
When updating or deleting, you do not have to pass all of the old and new
values. The API only needs to compare one value.
OVN allows transactions to occur across longer periods of time without holding
long- term database locks, for example, when working with distributed
applications.
User-Custom Forms
From Forms4.5 forward, two Forms can update different columns on the same
row: ON-LOCK compares only the queried and current attributes. This results
in no overlap between two sets of updated attributes, but the OVN would cause
an overlap. In delivered HRMS Forms this feature is not used and is not an
issue. Also, each Form can also process multiple rows in one commit unit.
These features demand that any user-custom Forms (truly custom forms, not
configured CustomForm) using APIs must handle OVN and locking.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 23

OVN Locking Example


OVN Locking Example

User 1

User 2

Database
Address id:1
OVN:1
Town:
Country: France

Address id:1
OVN:1
Town: Leeds
Country:

1-19

Address id:1
OVN:1
Town:
Country: UK

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

OVN Example
Sequence:
Both users query the same record, retrieving OVN 1
User A updates town to Leeds.
User A commits.
API locks row for update.
API: both OVN = 1; change is accepted, updating OVN in the table to 2.
User B updates country to UK.
User B attempts to save and commit.
API database locks.
API compare fails: table OVN is 2, user B has OVN 1.
User B requeries record, retrieving the latest OVN value of 2.
User B updates record again.
OVN match; change is accepted.
Table accumulates both changes.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 24

Using APIs: Unique Parameters


Using APIs: Unique Parameters
Most parameters documented in package header
Use SQL*Plus to describe the API
Most of the parameters map to a database column
in the HRMS schema

1-20

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Unique Parameters
The parameters for each API can be found in the documentation of the package
header, or by using SQL*Plus to describe the API. Each API has a set of
parameters that may or may not be specified. Most of the parameters map to a
database column in the HR schema. You can become familiar with the
parameters by examining the views behind various application forms, or as you
investigate tables in HRMS.
Note that the variable for any IN OUT parameter must be included in the API
parameter calling list.
Note also that parameters may change depending on which API is called. For
example, p_employee_number will be IN OUT for creating an employee, but
only IN for update.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 25

API Layers
API Layers
Custom / Alternative Interface layer

Business Process layer


Published APIs
Oracle Applications
Internal Code Layers

Business Support layer

Row Handler layer

1-21

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Four distinct layers:


Custom/Alternative Interface Layer
This layer provides specific parameter names and is required when database
column meanings vary, depending on the context value.
Business Process Layer
Each procedure handles one business function as a single transaction:
everything either succeeds or fails. Processing steps are carried out by
calling other layers (Row Handlers, Business Support Layers, or Business
Process Layers).
Business Support Layer
Required when two or more business processes contain a common
processing unit.
Row Handler
Contains procedures for validation, insert, update, delete, and lock for a
single database table.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 26

API Layers Example


API Layers Example
create_gb_employee

create_employee

create_us_employee

Custom /
Alternative
Interface

hire_contact

Business
Process
Layer
Business
Support
Layer

create_default_emp_asg
Ins Upd Del Lck

Ins Upd Del Lck

Ins Upd Del Lck

Person

Assignment

Element Entries

1-22

Row
Handler
Layer

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

API multiple layers, errors, and messages


Exception handling is needed to troubleshoot multiple API layers, this produces
messages.
when others;
hr_batch_message_line_api.create_message_line
(p_batch_run_number => l_batch_run_number
,p_api_name=>hr_person_address_api.create_person_
address
,p_status => F
,p_error_number => sqlcode
,p_error_message => sqlerrm
,p_extended_error_message => fnd_message.get
,p_source_row_information => to_char(sel.rowid)
,p_line_id => l_dummy_line_id);
end; --end exceptions
View process errors in HR_API_BATCH_MESSAGE_LINES, as follows:
select * from hr_api_batch_message_lines abm
where abm.batch_run_number = :batch_run_number
order by abm.line_id;

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 27

API Usage: Options and Guidelines


API Usage: Options and Guidelines

Initial Data Upload


Multivendor Solutions
Customer Specific Forms and Localizations
Spreadsheets and desktop interfaces
Exception Handling
Commit

1-23

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

API Usage
Initial Data Upload: When a customer purchases Oracle HR, APIs can be used
to migrate data from the legacy system without data entry clerks. You can map
data to the API parameters, load legacy data into staging tables, then call APIs
to actually populate the Oracle HRMS tables.
Multivendor Solution: Purchased applications may use different vendors. A
change in one application affects another. Instead of the user having to
remember changes, updates are applied electronically either immediately or
with the next updated batch.
Customer Specific Forms: Localization may require customers to change the
Forms which are supplied by rearranging display order or removing unwanted
fields. Changes will not have application support unless additional manipulation
of Oracle HRMS data is performed using public APIs.
Spreadsheets: You can export Human Resources data from working
spreadsheets to text files, load the data into tables, and then upload the data
using APIs.
Exception handling as described previously.
Note that commit must be handled by user scripts: API success does not commit
transactions.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 28

Web Browser and API to Insert Data


Web Browser and API to Insert Data
Web Browser Communicates with Application
Server
Server Specifies API Wrapper
Wrapper calls API

WebServer
Application
Server

Wrapper
API

1-24

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Web Browser and APIs


HTML for Web Browser: Web browser expects to receive HTML containing
one of the following: error details, confirmation success, or next screen/page.
However, APIs do not generate HTML.
Exception Handling
If the data retrieved fails the API validation, a PL/SQL exception is raised. Left
unhandled, the Web context-type: text/HTML error builds the error text in
HTML Security
HTML alone is not secure. To protect the application you require extra security
features which are not part of the API. Parameter Security can be enforced when
HTML is viewed, the browser encrypts sensitive values and de-encrypts on the
server.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 29

APIs and Wrappers


In this discussion, we refer to HRMS delivered code that calls APIs as
wrappers; this is not the user-defined code that calls a publicly callable HRMS
API.
The Web browser specifies the HRMS API wrapper: the browser
communicates with the Application Server, the URL identifies the wrapper.
Oracle Application Server calls the wrapper, which, in turn, completes Security
Checks, Parameter de-encryption, and conversion. The wrapper is a PL/SQL
procedure that calls the API.
Wrapper Calls API: Application Logic called by the API builds the HTML
returned by the Oracle Application Server, which then returns the HTML to the
Web Browser.
Technical Note
The middle tier (Application Server in the diagram above) code is implemented
in Java. When the end user submits a transaction, such as creating new data, the
Application Server calls a PL/SQL wrapper procedure in the database. This is
performed by going through a code layer known as JDBC (Java DataBase
Connectivity).
JDBC restrictions include inability to call PL/SQL procedures that use Boolean
parameters. Since all HRMS PL/SQL APIs have at least one Boolean parameter
(p_validate), PL/SQL wrapper is required to work around this and other
restrictions. The wrapper calls the publicly callable PL/SQL APIs to complete
database changes.
User code to publicly callable APIs are supported; calls to delivered wrappers
are not supported.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 30

Practice: Calling HRMS APIs


Practice: Calling HRMS APIs

Using SQL*Plus, create an employee by calling an


API and passing the appropriate parameters
Consider how the parameters match required fields
Verify your employee in the Person and Assignment
windows

1-25

Copyright Oracle Corporation, 2001. All rights reserved.

Performing This Practice


For detailed instructions on performing this practice, see Practice: Calling
HRMS APIs.

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 31

Additional API Reference Information


Additional API Reference Information
Specific Notes for Using APIs
Frequent Conflicts
Hints and Tips

1-26

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Common Issues, Hints, and Tips


One of the most frequent issues running APIs for historic data loading is
conflicting but real dates that result in datetracking issues. If employee,
organization, or other entities have conflicting dates, APIs will fail.
For example, entering employee data for employees who were hired before their
current supervisor will cause an error if you try to insert the employee record
and include the supervisor with the employee hire date (before the supervisor
was available).
As a work-around you need to first call the API to create the employee without
the supervisor_id and commit. Next, create, enter, and commit the supervisor.
You can then call the hr_assignment_api.update_emp_asg to include the
supervisor_id, using the effective date for the supervisor and the
date_track_update_mode parameter value of UPDATE. Similarly, to include
a terminated assignment on a payroll, you need to insert an active assignment
with the payroll, then update and terminate the assignment.
Salary Upload API and the Maintain Salary Proposals API are normally used
differently: one difference corresponds to the conditional access of the salary
approval flag in forms. The Maintain Salary Proposals API includes an
approval parameter; this API is often used with restricted (SQL*Plus) access,
such as for initial data conversion.
The alternate Salary Upload API does not support salary administration
approvals. This API has more parameters, corresponding to finer control of
salary administration components. The Salary Upload API is the preferred API

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 32

for uploading salary proposal information when data crosses application


security limits. For example, you can use this API when data is exchanged
(external to the HRMS application) to a client machine using ADE (Application
Data Exchange).
API and Alerts: if an event-based alert is defined on a table accessed by an API,
the API will error. Two possible solutions are: disable the Alert, run the API,
then re-enable the Alert; alternatively, you can call fnd_global.apps_initialize,
then call the API.
In Release 11i the HR_EX_EMPLOYEE_API. actual_termination_emp
procedure requires a payroll for benefits assignment, regardless of whether
Benefits is installed. The resulting message indicates the requirement:
ORA-20001: Cannot default the monthly payroll for the benefits assignment.
The business group must have a default monthly payroll assigned. Define a
default monthly payroll for the business.
At assignment termination, an assignment row of type 'B' is created. Benefits
assignments are linked to the default monthly payroll in order to calculate
premiums for continuing benefits (such as COBRA in US). The workaround is
to do the following:
Step 1: Create a payroll with a period type Calendar Month
Navigate to HR application > Work Structures > Organization > Description.
Step 2: Query the Organization.
Step 3: Select the Business Group on the bottom of the form
Step 4: Highlight the classification for Business Group
Step 5: Select Others
Step 6: Select Benefits Defaults
Step 7: Select the Default Monthly Payroll defined in Step 1.
Loading Data: The easiest way to load large numbers of records quickly via
APIs is to use a staging table to hold the information to be loaded. This table
should be created in the HR schema and include all of the non-defaulted
parameters and any defaulted ones that you many want to enter.
APIs in Shared Install
Frequently when implementing a shared installation of HR, you want to convert
person data. Since shared HR is not datetracked, you need to know that APIs
are not supported in shared HR before R11i; they operate only in correct
mode.
R11i introduces the HR Foundation functionality, which delivers HR APIs that
can be used in shared installations with other applications. Information on
supported APIs, non-supported APIs, and special conditions for APIs is
available in HR Foundation and APIs in the HRMS API Toolkit, available on
Metalink.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 33

Summary
Summary
Having completed this lesson you should be able to
Identify publicly callable business process APIs in
Oracle HRMS
Identify and use API parameters and
Use HRMS public APIs with SQL scripts

1-27

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Summary
APIs are the basis of most interface tools for HRMS, and you will find frequent
use for them.
Please note that you can use only the APIs on the published list.
Recall that there are historic reasons that all standard HRMS Forms do not call
APIs; however, all of Self-Service is based on APIs.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 34

HRMS Data Pump

HRMS Data Pump

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 35

Objectives
Objectives
After completing this lesson, you should be able to do
the following:
Describe Data Pump and its relation to APIs
Recognize steps to implement and use Data Pump
Identify Data Pump Processes

1-29

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 36

Agenda
Agenda
Data Pump and APIs
Setting up Data Pump
Processes

1-30

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This lesson describes the HRMS Data Pump utility, which uses the HRMS
APIs. Setting up Data Pump, running the processes including the Data Pump
Engine concurrent process are discussed.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 37

Data Pump
Data Pump
HRMS Data Ext

Map data to API parameters


Calls APIs
Single interface table
Uses values or User Keys, not codes

API

Data
Pump

External
System
1-31

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Pump Overview


This utility provides full validation that can include your own custom
extensions to the APIs. Data Pump can simplify data loading for conversions or
interfaces.
This diagram presents a simplified view of how Data Pump works with APIs for
interfacing into HRMS tables. External data is mapped through Data Pump
views to API parameters. Data is moved in batches from the interface tables.
The Data Pump process calls APIs and other hooked validation, moving data
into HRMS tables.
We will drill into these components in more conceptual detail.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 38

Advantages of Data Pump


Advantages of Data Pump
Shields user from data structures
Can use API user hooks
Concurrent Process
Error handling
Restartable

Supports explicit user ordering of operations

1-32

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Pump
Data Pump provides several advantages over writing SQL API scripts: A major
advantage of Data Pump is that, in most cases, you can define and use actual
values instead of IDs for API parameters: Data Pump automatically translates
values into IDs.
Because you map data to the parameters of the APIs, you do not need to know
the complexity of the HRMS data model.
Data Pump provides predefined batch tables and standard processes.
The Data Pump Engine is a concurrent process, for which you can enable
parallel processing by setting the PAY_ACTION_PARAMETERS parameter
THREADS value.
Technical Note
The threads value includes the master or starting process. If you set a value of
two, the main engine code will start the master and add one slave process to
make the total of two concurrent processes. When running in parallel, it is
normal that the master process can finish before the slave processes

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 39

Components of the Data Pump


Components of the Data Pump

Meta Mapper
A set of tables
A set of views
Data Pump PL/SQL interfaces
Data Pump engine

1-33

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Pump Components


When you map data to Oracle HRMS, Data Pump allows you to set a User Key
value, a unique character string, for cases in which an ID value for an Oracle
entity cannot be derived from a logical unique key or name.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 40

Data Pump Components


Data Pump Components
Database

Data Pump Routines

Meta Views

APIs

Batch Header Table


Batch Line Table

1-34

Application
Tables

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

PL/SQL Routines
Meta-Mapper delivers and generates separate PL/SQL routines for each API
supported by Data Pump. You use those routines to insert data into the Data
Pump batch tables.
HR_PUMP_UTILS.CREATE_BATCH_HEADER( )
HRDPP_<API Procedure Name>.INSERT_BATCH_LINES
For example, HRDPP_ CREATE_EMPLOYEE .INSERT_BATCH_LINES.
HELP
A Help routine, HR_PUMP_META_MAPPER.HELP ( <package_name>,
<procedure_name>), provides detailed information on parameter options for
specific procedures. Viewing the help information identifies which parameters
are required, which have lookups, default values and so forth.
The Data Pump Engine Process
The Data Pump process is a standard concurrent process that performs the data
validation and loading operations. Some of the payroll process parameters that
impact data pump are THREADS, CHUNK_SIZE, and
MAX_ERRORS_ALLOWED.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 41

The Meta Mapper


The Meta Mapper
Generates meta layer views and procedures
Modes
Generates for supported APIs
Generate for a single API

1-35

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Meta Mapper
Meta Mapper is similar to an install process; it normally runs automatically,
creating views with HRDPV_ prefix. The process needs to be complete before
you load data using the predefined APIs. However, you can manually generate
the meta layer for all supported APIs using the following PL/SQL command.
SQL> execute hr_pump_meta_mapper.generateall;
Or, you generate the meta layer for a single APIs using the following PL/SQL
command.
SQL> execute hr_pump_meta_mapper.generate
(<package_name>,<procedure_name>);
For example:
SQL> execute hr_pump_meta_mapper.generate
('hr_employee_api', 'create_employee');
Technical Note
Note that not all publicly callable APIs are supported by Data Pump. Please
refer to Metalink for current information.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 42

Data Pump Interface Tables


Data Pump Interface Tables
HR_PUMP_BATCH_HEADERS
HR_PUMP_BATCH_LINES

1-36

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Pump Interface Tables partial listings


HR_PUMP_BATCH_HEADERS
BATCH_ID
Sequence generated unique ID
BATCH_NAME
Unique name for batch
BATCH_STATUS ACTION_STATUS lookup
HR_PUMP_BATCH_LINES
BATCH_LINE_ID Sequence generated ID
BATCH_ID
FK to batch headers table
API_MODULE_ID FK to HR_API_MODULES
LINE_STATUS
U/C/E/V
USER_SEQUENCE Controls processing order
LINK_VALUE
Important in parallel loads
PVAL001
Data item field (001 through 230)
The P_USER_SEQUENCE parameter controls the batch line processing order.
This sequence must equal the sequence required by business rules, such as
creating an employee before loading salary.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 43

Data Pump User Key Table


Data Pump User Key Table
HR_PUMP_BATCH_LINE_USER_KEYS
Concepts and Restrictions
Unique
Reusable
Can be Combined
Define Using Data Pump or Manually

1-37

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

User Keys
Data Pump lets you define the unique combination of items to identify records
for loading into HRMS. For example, when you are loading Person data, you
may use a combination of Last Name, First Name, Date of Birth, Gender, and
National Identifier to uniquely identify that person. USER_KEY_NAME is
literally the user key that you define.
Defining Keys: You must define parameter user key values with a name ending
in 'user_key'. Data Pump will resolve these values into _IDs for the HRMS
system records. The parameter may have type USER_KEY, implicit type is
VARCHAR2.
Note that the user_key_name must be unique in the entire database, not just in
each business group and unique across entities. For example, you cannot use a
Person user key value of SMITH987', and an Assignment user key value also
of 'SMITH987'.
You can define many different user keys for the same system ID. If you load
data from different external systems, you do not need to make the unique keys
match.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 44

You can use the same key with multiple APIs to update an existing entity, or to
specify another entity. For example, two person user keys can specify a contact
relationship.
For example, create_employee requires you to supply values for
p_person_user_key and p_assignment_user_key. When creating HRMS
records, Data Pump automatically inserts your key values and the HRMS APIgenerated key values into the user keys table.
The table HR_PUMP_BATCH_LINE_USER_KEYS holds key definitions,
important columns are:
USER_KEY_ID
Sequence generated ID
BATCH_LINE_ID
FK to batch lines table
USER_KEY_NAME
Actual key value
For subsequent actions, Data Pump can use the same keys to match records
between your external system and Oracle HRMS.Therefore, use caution when
purging the user key values table. For example, deleting assignment and person
user keys would prevent you from creating a secondary assignment for that
employee. You would first need to use the add_user_key procedure to recreate
the purged user keys.
Two ways to create User keys:
1. Data Pump Inserts New User Keys
You specify user keys for several API parameters. When an API is called
successfully, a new record is created. Data Pump then inserts a new row in the
user keys table, with the name you specified and the system ID value, which is a
PL/SQL OUT parameter returned from the API.
2. Manually Insert a New User Key
If you have already loaded data from an external system, or you want to create
multiple user keys for the same system ID, you can manually insert rows into
HR_PUMP_BATCH_LINE_USER_KEYS using the
ADD_USER_KEY_UTILITY procedure.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 45

Data Pump Tables


Data Pump Tables
HR_PUMP_BATCH_EXCEPTIONS Includes
Exception Level
Exception Text

1-38

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Exceptions
Processing errors are generated in HR_PUMP_BATCH_EXCEPTIONS.
When loading batch lines with related data, some operations must be performed
in a restricted sequence. For example, entering salary information for an
employee must take place after the employee record has been created. With
Data Pump, you use the P_USER_SEQUENCE parameter to control the order
of processing batch lines.
Note that Data Pump accepts sequence numbers that you enter; it does not
validate them. It attempts to process in the order you define. If you use
numbers that represent an invalid sequence, the process may return validation
errors when it tries to load data.
HR_PUMP_BATCH_EXCEPTIONS
EXCEPTION_SEQUENCE Generated Sequence ID
EXCEPTION_LEVEL
MESSAGE_LEVEL lookup
SOURCE_ID
BATCH_ID or BATCH_LINE_ID
SOURCE_TYPE
BATCH_HEADER / BATCH_LINE
EXCEPTION_TEXT
Text of Exception

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 46

Data Pump Tables


Data Pump Tables

HR_PUMP_REQUESTS
HR_API_MODULES
HR_PUMP_MODULE_PARAMETERS
HR_PUMP_DEFAULT_EXCEPTIONS
HR_PUMP_RANGES

1-39

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HR_PUMP_REQUESTS
This table is accessed when you run in debug mode.
BATCH_ID
FK to HR_PUMP_BATCH_HEADERS
REQUEST_ID
Concurrent manager request ID
SESSION_ID
session ID
PROCESS_TYPE
MASTER/SLAVE
HR_API_MODULES
This table holds API module details (procedures); it is not a specifically a data
pump table.
HR_PUMP_MODULE_PARAMETERS
This table contains details of API parameters required by the meta mapper for
generating views and PL/SQL procedures.
HR_PUMP_DEFAULT_EXCEPTIONS
This table contains details of API modules not conforming to parameter
defaulting rules.
HR_PUMP_RANGES
This table contains parallelization control information.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 47

Data Pump Views


Data Pump Views
Meta Mapper creates views

Views created for supported API procedures


Views used by Data Pump procedures
Columns in all views
Other columns

1-40

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Meta Mapper-Created Views


Meta Mapper creates views for each supported API procedure, based on
HR_PUMP_BATCH LINES, named HRDPV_<API Procedure Name>. For
example, HRDPV_CREATE_EMPLOYEE is the view created for the
create_employee API. These views are used by Data Pump procedures and are
available for you to access.
All views have the following columns:
BATCH_ID
BATCH_LINE_ID
API_MODULE_ID
LINE_STATUS
USER_SEQUENCE LINK_VALUE
There may be other columns you can easily recognize, such as:
P_EFFECTIVE_DATE
P_ATTRIBUTE1
P_PAYROLL_NUMBER
P_LAST_NAME
P_PERSON_USER_KEY
P_ORGANIZATION_NAME
P_JOB_NAME
P_ASSIGNMENT_NUMBER
P_ASSIGNMENT_USER_KEY P_DATETRACK_UPDATE_MODE

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 48

Generated PL/SQL Interfaces


Generated PL/SQL Interfaces
Meta Mapper generates packages for each API
INSERT_BATCH_LINES
Data Loading to batches

CALL
Convert name to ID
Review and confirm data

1-41

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Meta Mapper
The Meta Mapper also generates a separate package for each API. These
packages are used to move data to the Data Pump batch lines, and
simultaneously to map names to the IDs required for APIs. These packages
allow you to easily load data into the batch lines and to review the content for
specific APIs.
For example, consider the package hrdpp_create_employee. The package
contains two procedures, the first named with INSERT_BATCH_LINES,
such as:
HRDPP_CREATE_EMPLOYEE.INSERT_BATCH LINES.
The second is named CALL. This wrapper procedure is used by the Data Pump
engine; it converts user key names to IDs.
Technical Notes
Direct calls to the CALL procedure are not supported.
For a few values, data pump does not use names having user-defined meanings.
The P_ATTRIBUTEx, included on the previous page, is one such occurrence.
You need to record the meanings of attributes (descriptive flex segments),
which is available from conversion mapping.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 49

Data Pump Process Utilities


Data Pump Process Utilities

Data Pump Routines

Meta Views

APIs

Batch Header Table


Batch Line Table

1-42

Application
Tables

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

PL/SQL Routines
Meta-Mapper delivers and generates separate PL/SQL routines for each API
supported by Data Pump. You use those routines to insert data into the Data
Pump batch tables.
HR_PUMP_UTILS.CREATE_BATCH_HEADER( )
HRDPP_<API Procedure Name>.INSERT_BATCH_LINES
For example, HRDPP_ CREATE_EMPLOYEE .INSERT_BATCH_LINES.
HELP
A Help routine, HR_PUMP_META_MAPPER.HELP ( <package_name>,
<procedure_name>), provides detailed information on parameter options for
specific procedures. Viewing the help information identifies which parameters
are required, which have lookups, default values and so forth.
The Data Pump Engine Process
The Data Pump process is a standard concurrent process that performs the data
validation and loading operations. Some of the payroll process parameters that
impact data pump are THREADS, CHUNK_SIZE, and
MAX_ERRORS_ALLOWED.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 50

Data Pump Engine


Data Pump Engine
A process initiated from the Concurrent Manager
Batch name
Validate flag

1-43

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

The Data Pump Engine Process


This concurrent process performs data validation and upload; it has: Debug
options, Logging capability, Batchname and Processing Mode parameters.
Access
Access the Data Pump Engine from the Super HRMS Manager responsibility:
(N) > Processes and Reports > Submit Processes and Reports > (L) Data
Pump Engine
Validate or Load
Data Pump can be used to call the APIs in validate mode, allowing you to
confirm data, processing sequence, and setup. A row is created in
HR_PUMP_BATCH_EXCEPTIONS when an error occurs. You can query
rows in SQL*Plus, selecting rows with LINE_STATUS = E from
HR_PUMP_BATCH_LINES.
After correcting problem, rerun the batch by submitting the Data Pump process
again using the same batch name. The process can b e submitted repeatedly
until all lines are successfully completed. Batch lines with a status of E- error;
U- unprocessed; or V- valid are automatically reprocessed; C - completed
(successful). You do not have to take any action to remove rows from the
exception table.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 51

Logging Options
Logging Options
PAY_ACTION_PARAMETERS table
Data Pump Parameter PUMP_DEBUG_LEVEL
PYUPIP: Oracle HRMS trace

1-44

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Parameters and Logging Options


PAY_ACTION_PARAMETERS values impact the concurrent process. Some
of the parameters to consider for data pump are: THREADS for multiple
processes; MAX_ERRORS_ALLOWED controls the number of errors
permitted in a calling API before the Data Pump engine marks the complete
batch in error; CHUNK_SIZE - controls how many batch API calls are
processed at a time
Data Pump Logging Options
Logging Options are set in PUMP_DEBUG_LEVEL, values include:
MSG - Output-specific logging messages frequently used
ROU - Procedure routing information - frequently used
WCD - Wrapper cache debugging log
AMD - API module debug
STK - Stack dump logging
EXT - Exit information frequently used
RRI - Range row insert logging
RRP - Range row processing logging
GID - GET_ID function failure information

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 52

Running PYUPIP
Running PYUPIP
Determine request ID for running process
Run PYUPIP

1-45

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HRMS Trace Utility


You can use the Oracle HRMS trace utility (PYUPIP) to view logging output
during a run. If using PUMP_DEBUG_LEVEL, note that ROU uses the
HR_set_location utility.
Determine the actual concurrent manager request ID for the running process
select * from hr_Pump_requests;
Typical Output:
BATCH_ID
REQUEST_ID
PROCESS_TYPE
8437
98533
MASTER
8437
98534
SLAVE
Run PYUPIP
$PAY_TOP/bin/PYUPIP <username/password>
REQID<request id>
For Example
$PAY_TOP/bin/PYUPIP apps/apps REQID98534

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 53

Data Pump Key Features


Data Pump Key Features

Actual values, not codes


Explicit user operation ordering
Rerun capability
Validate only mode
Defined user keys
Automatic parallelization
Logging options

1-46

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Summary of Features
Actual values, not codes, for example:
- P_PAYROLL_NAME instead of P_PAYROLL_ID
Supports explicit ordering of operations with P_USER_SEQUENCE
Rerun and Resubmit Batch process capability
Redo unprocessed or errored lines
Run in validate only mode
User Keys are defined for complex logical keys, such as person and address
Automatic parallelization
Insert/update a row for the THREADS parameter in
PAY_ACTION_PARAMETERS
Technical Note:
When using parallel processing, use the P_LINK_VALUE parameter in the
batch lines to group transactions that must be run within the same thread. Good
practice is to load unrelated data in separate batches.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 54

Data Pump Loading Tips


Data Pump Loading Tips

Date parameters
Boolean parameters
Out parameters
User keys
Mandatory parameters
Flexfield attribute parameters

1-47

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Pump Loading Tips


Date parameters passed to INSERT_BATCH_LINES must be in the MLScompliant format YYYY/MM/DD
Boolean parameters passed to INSERT_BATCH_LINES must be in the
format True or False.
Out parameters are updated in the view by Data Pump after a record has been
successfully loaded
Mandatory parameter values must be passed to the
INSERT_BATCH_LINES procedure

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 55

Data Loading Data Flow


Data Loading Data Flow
Database
Data Pump Routines

Meta Views
Batch Header Table
Batch Line Table
DATA
FILE(s)

SQL
Loader

Custom
Program

APIs

Application
Tables

1-48

Custom Conversion Table(s)

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Flow Summary


Start by determining the APIs that will be required for your data load.
User Keys for Data Pump are identified or defined.
Data Pump Meta Views are created
Interface tables are loaded in batches
At this point, the Data Pump Engine is run, submitting the Data Pump process
from the SRS window; the process (equivalent to using the API p_validate
parameter) can validate or can validate and populate the HRMS tables.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 56

Practice: Loading Data Using Data Pump


Practice: Loading Data Using Data Pump

Follow the demonstration, or use the notes provided,


to load data using Data Pump
(N) > Processes and Reports > Submit Processes and Reports
(Select) Single Request > (LOV) Data Pump Engine

1-49

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Online Help
For details on how to complete the Submit a New Request window please refer
to the on line Help path :
(Help) Oracle HRMS > Getting Started and Using Oracle Applications >
Submitting a Request

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 57

Summary
Summary
Having completed this unit you should be able to:
Explain the relation of Data Pump and APIs
Describe benefits of using Data Pump
Use Data Pump

1-50

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

APIs and Data Pump


Chapter 7 - Page 58

Interface Tools and


Utilities
Chapter 8

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 1

Interface Tools and Utilities

Interface Tools and Utilities

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 2

Objectives
Objectives
After completing this unit, you should be able to do
the following:
Identify HRMS input and output features including
HRMS Mass Information Exchange (MIX)
HRMS data flows with Payroll Interfaces

1-2

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This unit describes the HRMS interface utilities and tools. APIs are the primary
building block for most interfaces. There are additional tools built upon APIs,
as well as separate utilities for different components of HRMS, including
interface tables for batch element entry.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 3

Agenda
Agenda
Interface utilities
MIX (Mass Information eXchange):

BEE (Batch Element Entry)


System Data Extract
ATG (Application Technology Group) Data loading
tools
Payroll Interfaces

1-3

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Note
MIX end-user functions are covered in other HRMS courses:the focus here is
on options to use, extend, or configure for core HR data.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 4

BEE: Batch Element Entry

BEE: Batch Element Entry

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 5

Objectives
Objectives
At the end of this lesson you should be able to:
Identify Tables used in BEE
Understand the BEE process for Element Entry

1-5

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 6

Agenda
Agenda

BEE (Batch Element Entry) Terminology


Tables
Processes
Extension Options

1-6

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

MIX (Mass Information eXchange) BEE (Batch Element Entry)


MIX is the term delivered in the HRMS system to include BEE (Batch Element
Entry) and the Data Extract. While BEE is used primarily for payroll elements
and the Data Extract for Benefits information, both processes are available as
part of core HRMS and can be used for data exchange.
The delivered core HRMS BEE process can be used for regular and exception
element entries. The steps are included in end user training and available in
Online Help. However, the focus of this lesson is to identify tables and
processes so technical implementors may understand where extension options
are available.
The term employee is used in this lesson: BEE can accept assignment sets and
processes element entries for each assignment.
Note for OFHR (Oracle Federal HR):
You can create and update element entries, including non-RPA (Request for
Personnel Action) enrollment and time capture with BEE. Those entries are
included in OFHR element entry history.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 7

BEE: Batch Element Entry


BEE: Batch Element Entry

BEE (Batch Element Entry)


Load tables: Pay_Batch_Element_Entry_API
Element entry in batches
Process includes validation

1-7

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

BEE Function and Validation


Element entry information can be submitted through BEE. When a user enters
information through the BEE windows, HRMS system validation is performed
as if the data had been entered using element entry windows. BEE allows
optional user validation such as Control Totals and Additional Business Rules.
Background:How BEE is used
BEE tables have a Pay_ prefix, but can be used for non-payroll purposes, too:
regular element entry in batches
updates, new entry, and one-time changes on recurring elements
timecard entries requiring input for hours, location, or other values
additional entries in a particular period
absence entry, which creates both absence records and element entries.
Batches
Each batch requires a header and allows an unlimited number of lines, one line
for each element entry for each assignment. A batch can contain lines created
through different entry methods and with various effective dates.
Loading BEE Tables
You can load data into the batch lines table using the
PAY_BATCH_ELEMENT_ENTRY_API, or other interfaces such as PL/SQL,
SQL*Loader. Both headers and lines tables have status identifiers:
BATCH_STATUS and BATCH_LINE_STATUS , respectively.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 8

Processes
Once tables are loaded, the BEE process includes a validation option that
confirms assignment numbers and verifies required and formula validated input
values.
Control Totals and Additional Validation
Predefined control totals check the number of batch lines in a batch and verify
the sum of pay values and hours. You can create control totals for other
numerical element input values by defining a value for the _CONTROL_TYPE.
This is discussed further in this lesson.
Transfer to Entries Table
When the batch is ready for transfer to the database, you run the BEE transfer
process from the Batch Header window. This process validates then transfers
entries from the PAY_BATCH_LINES table to the Entries tables in Oracle
HRMS.
Batch Statuses
The batch status relates to the status of the batch header, all batch lines, and any
batch control totals. The following status values are possible:
Valid: All of the lines, control totals, and header are valid.
Transferred: all batches are transferred
Unprocessed: At least one line, control total, or the header is unprocessed.
Error:At least one line, control total, or the header is in error.
Status Mismatch: The combination of statuses in the header, lines, and batch
is not consistent.
Note: When entry is limited to the Batch Header and Batch Lines windows,
status mismatch is prevented.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 9

Batch Element Entry Tables


Batch Element Entry Tables

PAY_BATCH_HEADERS
PAY_BATCH_LINES
PAY_BATCH_CONTROL_TOTALS
PAY_MESSAGE_LINES

1-8

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

PAY_BATCH_HEADERS
Headers include information uniquely identifying each batch.
PAY_BATCH_LINES
This table hold lines of data for each BEE batch, corresponding to one entry for
each element for each assignment.
PAY_BATCH_CONTROL_TOTALS
Control totals are user-defined information to validate batch data.
PAY_MESSAGE_LINES
These hold details of messages produced while running the process. The
SOURCE_TYPE of the message can be identified by a single letter.

C - Batch Control level

H - Batch Header level

L - Batch Line level

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 10

BEE: PAY_BATCH_HEADERS
BEE: PAY_BATCH_HEADERS
Key Columns
Result: BATCH_STATUS
Process Rules:

ACTION_IF_EXISTS
REJECT_IF_FUTURE_CHANGES
Identification:

BATCH_ID
BATCH_SOURCE

1-9

Copyright Oracle Corporation, 2001. All rights reserved.

Key Columns
BATCH_NAME
BATCH_STATUS

E = Error

T = Transfer

U = Unprocessed

V = Valid

W = Warning
ACTION_IF_EXISTS

I = Insert

R = Reject

U = Update
DATE_EFFECTIVE_CHANGES

C = Correct

O = Update/Override

U = Update/Change Insert
PURGE_AFTER_TRANSFER: Y/Yes or N/No
REJECT_IF_FUTURE_CHANGES: Y/Yes or N/No

I
A

&
l
a

y
l
n

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 11

O
e

BEE: PAY_BATCH_LINES
BEE: PAY_BATCH_LINES
Key Columns
Line Identification

Element Type
Entry Type
Batch Line Status

1-10

Copyright Oracle Corporation, 2001. All rights reserved.

Key Columns

BATCH_LINE_ID

ELEMENT_TYPE_ID

ASSIGNMENT_ID

BATCH_LINE_STATUS

E = Error

T = Transfer

U = Unprocessed

V = Valid

W = Warning

ENTRY_TYPE

A = Additive Adjustment

B = Balance Adjustment

D = Additional Entry

E = Element Entry

R = Replacement Adjustment

S = Override

&
l
a

y
l
n

O
e

I
A

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 12

Additional Batch Validation


Additional Batch Validation
Control Totals
Additional Business Validation

1-11

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Predefined Validation
BEE Validation includes verifying that:
Employee exists on the transaction date and has element eligibility
Employee is not paid after termination
Override element validation
Transactions do not incur excessive pay
Total hours do not exceed weekly regularly scheduled hours
Changes in base rate for hourly time card entries
Sufficient accrual time for PTO pay
Cost center and labor distribution codes are mapped.
Control Totals for Numeric Input Values
End users can use predefined control types to validate a BEE batch against
numeric control totals for batch line count, sum of pay value entries, or sum of
hours entries.
End users can create additional control codes for other numeric input values, by
using the lookup type CONTROL_TYPE and adding a code using the naming
convention: _TOTAL_COLUMN_<input_value_name>_ and entering the
input value name for the meaning. The check will compare the entry to the sum
of the numeric values for that named input value.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 13

Other Validation
You can specify business rules in PL/SQL in pyusrchk.pkh and pyusrchk.pkb to
validate the batch header, lines, and control totals. The file can be found under
$PAY_TOP/admin/sql,package PAY_USER_CHECK.
Control Values: You can define control values other than numeric sums, using a
different naming convention for the control lookup code.
Batch Header and Lines: Any validation that you can define in PL/SQL can be
implemented to check the batch header or lines.
Instructor Note select text from all_source where name =
'PAY_USER_CHECK and type ='PACKAGE BODY order by line

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 14

Practice: Using BEE in SQL*Plus


Practice: Using BEE in SQL*Plus

Create a BEE batch to add an entry for an employee


Process the batch
Verify the entry

(N) Processes and Reports > Submit Processes and Reports

1-12

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Online Help
For details on how to complete the Submit Requests Window please refer to the
on line Help path :
(Help) Oracle HRMS > Getting Started and Using Oracle Applications >
Submitting a Request
Instructor Note:
Inform the students that the first level in the Online Help path, which starts with
Oracle HRMS, should be substituted with their local Oracle HRMS menu tree
path level.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 15

Summary
Summary
Having completed this lesson, you should be able to:
Identify the BEE tables
Understand the BEE process
Know where to extend batch validation

1-13

Copyright Oracle Corporation, 2001. All rights reserved.

Additional Notes
Note that element entries can be deleted for employees using the API:
py_element_entry_api.delete_element_entry

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 16

System Data Extract

System Data Extract

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 17

Objectives
Objectives
After completing this lesson, you should be able to do
the following:
Identify options in HRMS MIX: System Data Extract

1-15

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This lesson describes the System Data Extract, which is delivered in core HR,
available in the menu as a MIX (Mass Information eXchange) function. The
extract is designed for Benefit information, but is available as part of core HR
and provides a powerful utility for extracting data without coding.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 18

Agenda
Agenda
System Extract

1-16

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Extract
Benefits Reporting Groups and Regulatory Definitions are covered in the
Standard and Advanced Benefits System Extract unit in certain Benefits
courseware. The intent of this lesson is only to introduce the Data Extract as an
option for HR or HRMS data extraction.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 19

Benefit System Data Extract


Benefit System Data Extract
Delivered as Core HR Function
Definition of Elements and Records
User-specified Criteria

Concurrent Manager process


Writes output file

1-17

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Extract and Results


The end-user can define an extract by selecting the data elements, their layout,
selection criteria, and other criteria for the extract (such as date ranges, whether
to select a full file or update from a previous extract). The data extract creates
flat files for communications, third-party interfaces, and other uses. Flexibility
of the extract has proven valuable for HR and Payroll data, as well as Benefits
information.
Overview of Major steps in the Data Extract:
Define the layout
Define the criteria
Define the extract
Run the Extract process
View the Extract results
Run the Extract Write process
For more information, see details for each of these six topics in the Online Help:
(Help) Oracle HRMS > Compensation Entry and Analysis > Total
Compensation > How to > Benefit Reports and System Extract
Instructor Note:
Inform the students that the first level in the Online Help path, which starts with
Oracle HRMS, should be substituted with their local Oracle HRMS menu tree
path level.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 20

Defining the Layout


Over 780 data items are available with user-friendly names (no knowledge of
tables and columns is required). Users define record layouts, which can be
combined and reused in various file formats. You can format data to the ANSI
834 format, a standard benefits interface layout (US).
The Data Elements tabbed region is where you select data elements and the
corresponding format for extract layout. Format options include:
Decode
String format
Totals
Rule (Extract Person Data Element discussed later in this lesson)
Defining the Criteria
An extract criteria Profile definition can be comprised of the following areas:
People
Benefits
Changes
Payroll
Communications
Advanced (Advanced is available to both Standard and Advanced Benefits)
Running the Extract, View Results, Write Extract
Enter the parameters (including output directory and filename) for your extract
and run the process from the Submit Reports and Processes window (further
documentation is available, but beyond the scope of this topic).
The output of a system extract run, including a summary, detailed results by
person, and run results errors, is available from the Extract Results window.
Run the Extract Audit Report from the Concurrent Manager to view a limited
selection of records from the extract results.
The Extract Write Process is also run from the Concurrent Manager. This is the
process which actually writes your file in the format you specify, to the
directory you identify as a parameter.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 21

Extract Definition:
Extract Definition:
Data Elements
Record Layout
File Layout

1-18

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Extract Definition
Before creating an extract, you need to determine the information you need,
selection criteria, and map those to the elements available. Extract data elements
are predefined and cannot be extended.
Data elements can be used repeatedly, and defined record layouts can be used in
multiple files. At the time of writing, there are about 800 data elements
available.
You can query the list of data elements using this SQL command:
Select substr(name,1,50) name, lvl_cd
from ben_ext_fld order by 1;
A hierarchy controls data element availability. The concepts of levels, branches,
and planes define the data extract hierarchy.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 22

Extract Levels
Extract Levels
Plane 1
Person
<branch>

Plane 2
Eligibility

Enrollment

Run Results

Element

Plane 3
Beneficiary

1-19

Dependent

Action Item

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Levels, Planes, and Branches


Level - a logical grouping of data elements; in this diagram, Eligibility and
Element can be identified as 2 distinct levels.
Plane - a grouping of levels; for example, Eligibility, Enrollment, Run Results,
and Element are levels in one plane.
Branches - branches link levels from the planes; the possible branches for an
extract are identified in this diagram; they are:
Person, Eligibility
Person, Enrollment, Beneficiary
Person, Enrollment, Dependent
Person, Enrollment, Action Item
Person, Element Entry
Person, Run
Extract Limits
Define a record with data elements from one branch level (not multiple levels in
a plane).

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 23

Extract Levels
Extract Levels
Data Extract Elements
Rule: Extract Person Data Element
Rule has Contexts
Rule can access Functions

1-20

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Extract Usage and Levels


The Data Extract is available for Oracle HR, Payroll, Standard Benefits, and
Advanced Benefits.
End-users can configure the Benefits Extract for various results, such as the
third-party information, communications, and other files. Because of the power
and flexibility in the Benefits Extract, you may find value in extending the use
of this extract.
Note: The extract denormalizes data by repeating data from higher planes for
each lower level. For example, if you want to extract Payroll balances and use
the element or run_results, the person information repeats for association with
each element or run_result.
Configuring or Extending Functionality of Extracts
FastFormula are identified as Rules in Benefits. Each Rule type requires certain
input values and returns specific values. When you select the value Rule for a
particular Benefits function in a Benefit window, corresponding Rules are
available from the list of values.
(See the section on Formulas for Benefits Administration in the Using Oracle
FastFormula manual for Benefit Rule types, input values, return value, and
contexts.)

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 24

Rule type: Extract Person Data Element


This Rule (or formula) should be used only if you want to include information
that is not one of the seeded data items. For the nearly 800 seeded data items,
this rule is not appropriate.
The Extract Person Data Element Rule can define a data element item based on
person or assignment information; also, this rule can calculate results on person
or assignment information.
The Extract Person Data Element Rule uses these contexts:
- Business_group_ID
- Effective_date
- Organization_ID
- Assignment_ID
- Jurisdiction_code (when legislatively required)
Note that contexts for Data Extract Rules do not enable access of dynamic
database items. You can use a function to access those items from within your
Rule.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 25

Summary
Summary
Having completed this lesson, you should be able to
do the following:
Identify options in HRMS MIX: System Data Extract

1-21

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 26

Data Loaders and Updates

Data Loaders and Updates

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 27

Objectives
Objectives
After completing this lesson you should be able to do
the following:
Identify Data Loaders
Discuss Mass Update Functions

1-23

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This lesson describes data loaders provided with Oracle Applications and
HRMS specific functions. The purpose of this lesson is to inform you of the
tools and reference information, including product direction.
Note about other data loaders
MIX: BEE (Mass Information eXchange: Batch Element Entry) and the Generic
Payroll Interface Kit: Forward Feed are covered in separate lessons. The Payroll
Interface Kit is in a separate lesson that includes both Forward Feed and
Backfeed.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 28

Agenda
Agenda
Data Loaders
ATG (Application Technology Group) Data loading
tools
HRDU (HR Data Uploader)
Mass Updates

1-24

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 29

Data Loaders
Data Loaders
Utilities used by Applications Development
Utilities Delivered with Applications
HRMS Utilities

1-25

Copyright Oracle Corporation, 2001. All rights reserved.

Data Loaders
The ATG (Application Technology Group) of Applications Development
maintains data loaders for use by various application product groups. These
include data loaders used for seed data, which are then delivered with the
applications in data files. HRMS customers can use certain data loaders for
specific entities, such as Extra Information Types; HR Development
conditionally provides direction for these utilities in localization efforts.

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 30

ATG Dataextract/Datamerge
ATG Dataextract/Datamerge
Used during core application installs, upgrades
Similar to export and import
With option to specify data

Define user developer keys


Has automatic key resolution features

1-26

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Dataextract and Datamerge


These utilities are used to insert, update, or delete data from the database and
are normally used with core Application installs. The following parameters are
available:
Insert Missing Rows
Update Unchanged But Customized Rows
Update Out-Of-Date Non-Customized Rows
Update Out-Of-Date Customized Rows
Update Customer Added Matching Rows
Resolve Mismatched Alternate Primary Keys
Delete Obsolete Non-Customized Rows
Delete Obsolete Customized Rows
Delete Customer Added Rows
Extract Where Clause
Developer Primary Key
The Developer Primary Key is a predefined column or set of columns. The key
remains the same for all customers and all releases; modifications are not
permitted.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 31

Datamerge
Datamerge can also be used independently of Autoinstall. The Datamerge utility
is located in $AD_TOP/bin; you run it from the directly from the product top
directory, where the install or import files are located.
For more information, see Metalink Note:1009726.6

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 32

ATG Data Loaders and APIs


ATG Data Loaders and APIs
APIs and Loaders
Loaders
Menus
EIT (Extra Information Types)
Messages

1-27

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ATG Data Loaders and APIs


HRMS Business Process APIs are used for HRMS-specific entities, such as in
converting legacy data or from an alternate user-interface. ATG Data Loaders
access Application foundation data.
FNDLOAD in addition to ATG use, this loader is used for EIT (Extra
Information Type) data, menus.
Starting with Release11i (11.5), loaders are used for all patches to AOL seed
data; SQL scripts are not used. Supported loaders in 11.5 are:
WFLOAD - All Workflow data, data file .wft
AKLOAD - AK data, data file .jlt
FNDMDGEN This loader moves all messages from the database into runtime
files
FNDLOAD - Generic loader for all other entities, data files .ldt. Menu data for
the top-level menu associated with a responsibility should be uploaded and
downloaded using FNDLOAD. All submenus of the top-level menu will be
included.
FNDLOAD configuration files for AOL entities can be found in

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 33

$FND_TOP/patch/115/import/*.lct. Configuration files for these loaders


contain usage documentation, including parameters that limit data, and identify
whether a full upload or only a translation upload (marked NLS Upload only)
is supported.
Entities supported include:
Concurrent Program Libraries and entities such as mime types, printers,
queues, request groups, request sets, program schedules, and program
workshifts.
Flex data, including: VALUE_SET, FLEX_VALUE_SET_NAME,
DESC_FLEX, KEY_FLEX
Lookup data: FND_LOOKUP_TYPE, including sub-entity
FND_LOOKUP_VALUE
Messages: FND_NEW_MESSAGES
On-Line Help Navigation Trees: FND_HELP_TREE
Multi-lang/currency/territory: FND_CURRENCY, FND_LANGUAGE,
FND_TERRITORY
Profiles, Profile Values, and Profile Options
Security data: FND_USER, FND_SECURITY_GROUPS,
FND_APPLICATION, FND_RESPONSIBILITY, FND_DATA_GROUPS
Technical Note: FNDSLOAD The Function Security Loader was used for
forms, functions, and menus; it is replaced by FNDLOAD and is provided only
for backward compatibility. Control files associated with FNDSLOAD are
named afsload.lct; data files are .slt.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 34

HR Data Uploader
HR Data Uploader
HRMS Data
Data in Spreadsheet
Data Pump process
Calls HRMS APIs

API

Data Pump
Process

Data
Upload
Process

Data
Pump

External
Data

HRDU

1-28

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HRDU HR Data Upload Overview


HR Data Upload processes data that is exported from a spreadsheet, moving it
into Data Pump tables. The keys are predefined for the delivered utilities, so
that you only run Data Pump processes.
This diagram presents a simplified view of the relation between HRDU, Data
Pump, HRMS APIs and HRMS tables. For example, the Start Skills flat files are
represented as the external data. The data files are loaded into Data Pump tables
by the HRDU process. Data Pump processes data from its tables, calling APIs,
which populate HRMS Competence entities.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 35

HRDU (HR Data Uploader)


HRDU (HR Data Uploader)
Payroll Backfeed
G/L HRMS Cost Synchronization*
SkillScape Competencies

1-29

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HR Data Uploader
This utility is provided for specific use in these limited areas of the HRMS
product:
The Payroll Backfeed, which is described as part of of the Generic Payroll
Kit, uses HRDU to move third party or external data into HRMS tables.
Another feature of HRMS that uses HRDU is synchronization of cost
allocation information with Oracle G/L. (Note that terminology for this
feature is subject to change, pending release.)
Competency Management in Oracle Training Administration interfaces with
SkillScape starter skills dictionary (third party product); the dictionary is
loaded using HRDU. For further information, please refer to the White
Paper entitled Installing the SkillScape Starter Skills Dictionary, available
on Metalink.
Technical Note:
HRDU is strictly limited to these uses; it is not available for customer use, such
as with HRMS APIs.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 36

SQL
SQL
SQL scripts
Third Party data
Legacy data
Staging tables

1-30

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

SQL scripts
You can use SQL to insert, update, and delete data external to Oracle
Applications data. For example, you may have interface or staging tables that
contain external or legacy data. You can correct data using SQL. You must use
APIs or an approved utility to move data into Oracle tables.
Note: Directly manipulating data in the Oracle HRMS tables violates Support
for the application. If an occasion occurs for which you think this is required,
you need to contact Oracle Support for assistance.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 37

Mass Updates
Mass Updates
Mass Updates
Across Organizations
Extend API logic with User Hooks

Mass Assignment Updates


Global and Legislative Versions

Mass Position Updates

1-31

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Mass Updates
These function allow end-users to query and make datetracked changes to many
assignments or positions at once. Users have comprehensive search criteria in
the professional interface (Forms), then also can remove subsets of the search
results before making changes. Datetracked update or correction can be
applied.
Assignments and positions within different organizations, but within one
Business Group, can be accessed together.
Attributes included in the HRMS APIs can be changed: there are global, US,
and UK versions of the Mass Assignment Update Form. The US and UK
versions allow access to update of the soft-coded legislation, such as GRE
fields.
Both successful commits and any errors raised by the APIs are identified: the
user can change an individual record and resubmit the change.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 38

Summary
Summary
Having completed this lesson you should be able to
explain other methods of data loading:
Dataextract/Datamerge
ATG Data Loaders and APIs
HRDU
SQL scripts
Mass Updates

1-32

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 39

Interface Direction

Interface Direction

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 40

Objectives
Objectives
At the end of this lesson you should be able to:
Identify interface types in Oracle Human Resources
Identify options and limits for HRMS interface types

1-34

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 41

Agenda
Agenda

Interfaces in Oracle HRMS


Who builds interfaces
Types of Interfaces
Future directions

1-35

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
Lessons dedicated to other interfaces such as APIs, MIX functions, Data
loaders, and the Payroll Interface Kit are covered separately. This lesson
provides basic information about interfaces, some specific and limited to certain
legislations, available with Oracle HRMS.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 42

Interface Builders
Interface Builders
HRMS Development partners
Consulting
Localization groups

1-36

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Interface Builders
Optimum interfaces provide a seamless integration of Oracle Applications and
applications external to Oracle, from other vendors and customers. These
interfaces are built through a number of sources such as:

Oracle Design and Migration Services (DMS) working with Oracle


Alliance members

Oracle Consulting

Applications localization groups


Outgoing Interfaces
Interfaces between Oracle Applications and third party applications are built by
sources such as:
Cooperative Applications Initiative (CAI) partners
Oracle Design and Migration Services (DMS) working with Oracle Alliance
members
Oracle Consulting Services
Applications localization groups.
Our focus in this lesson is on the Payroll Interface Kit.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 43

HR Development Interface Model


HR Development Interface Model

Outbound data: views


Inbound data: APIs
Supportable
Can be simple

1-37

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Outbound Data
Data uploaded to an external database or tables external to Oracle HRMS is
extracted through views. For example, the interface for US Ceridian Payroll
uses deduction views as in the following statement:
Select employee_number, company, deduction_descr, recurring_flag, amount,
deduction_limit
From hr_ceridian_deduction_v
Inbound Data
Data uploaded into Oracle HRMS uses APIs that validate data and update the
HRMS tables.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 44

Interface Types
Interface Types
Payroll

Oracle Payroll
Generic Payroll Interface Kit
Legislation-specific Payrolls
Delivered Third-Party Interfaces

Recruitment Training Administration


Time and Attendance

1-38

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Interface Types
Interfaces can be divided into types based on functions and impact on the
delivered system. Specific interfaces may have legislative limitations,
particularly for Payroll. Identifying interfaces available with Oracle HRMS
provides an advantage in presenting phased and complete solutions.
Payroll
The most tightly integrated payroll system with Oracle HR is Oracle Payroll.
The same data structures and processes are shared, eliminating duplicate data
entry. Oracle provides legislation-specific payrolls for an increasing number of
countries. In addition, Oracle delivers a Generic Payroll Interface Kit that
allows interfacing of third party payrolls with Oracle HR. The Generic Interface
uses different forms and entities than Oracle Payroll, allowing sites with
multiple payroll vendors to use both Oracle Payroll and third-party or custom
payrolls without conflict.
Interfaces for outsourced US payrolls include specific packages for: Ceridian,
ProBusiness, and ADP.
Competency Management
Oracle HR delivers upload facilities for the SkillScape starter skills dictionary.
The dictionary is loaded into competency tables for Oracle HR and Oracle
Training Administration.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 45

Employee Development
Online employee development package, eAdvisor PDI, can be accessed from
Oracle HRMS.
Tax Compliance
Vertex can be used by Oracle Applications for US address validation; Oracle
US Payroll fully integrates with Vertex for tax compliance.
Time and Attendance
In addition to Oracle Time and Labor, an application interface between Kronos
solutions and Oracle HRM uses the MIX: BEE interface. The interface maps
Timekeeper Central to Oracle Payroll. Data from HRMS can be downloaded
into the Kronos solution.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 46

Vendor-Specific Interfaces
Vendor-Specific Interfaces

HR Development involvement
Long-term relationship with partner
Incorporate into core product
Supported by Oracle

1-39

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Other Vendor-Specific Interfaces


For complete and current information, inquiries should be directed to your local
representative. Many of the products listed are limited to US usage.
Staffing and Skills Management: Resumix 5.3 and Resumix Interact.
Organizational Charting: TimeVision uses standard Business Views to build
organization charts with OrgPublisher.
Check Printing (US): Bottomline Technologies and Evergreen
IVR (Interactive Voice Response): Talx and Workforce Technologies
Affirmative Action (US): Criterion
GeoAccess: primary physician search
Authoria: Authoria HR, Authoria Benefits, Authoria AnswerWise for selfservice Benefits features
HireRight for Background Checking
FLS for employer tasks associated with payroll tax payments and filings, wage
garnishment processing, and W-2/1099 processing.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 47

Summary
Summary
Having completed this lesson you should be able to
Identify interface types in Oracle Human Resources.

1-40

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 48

Generic Payroll Interface Kit

Generic Payroll Interface Kit

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 49

Objectives
Objectives
At the end of this lesson you should be able to:
Describe Payroll Integration with Oracle HR
Discuss the Generic Payroll Interface Kit
Identify what can be configured and extended in the
Payroll Interface Kit

1-42

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Oracle HRMS Generic Payroll Interface Kit


This introduction provides information so that customers, implementors,
maintenance, and support personnel are aware of the design and function of the
payroll interface.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 50

Agenda
Agenda

Generic Payroll Interface Kit


Forward Feed
Backfeed
Delivered versions
Legislative and Specific

1-43

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Focus of this lesson


The Payroll Interface Kit is a combination of code and documents that guide the
implementation and configuration of a third-party payroll interface with Oracle
HRMS.
A Forward Feed of data from Oracle HR and Backfeed of external data into
Oracle HRMS are provided with the Oracle Payroll Interface kit.
Note: Use of the kit is restricted, but supported.
This lesson focuses on basic information about the Payroll Interface: how it fits
with Oracle HRMS and Oracle Payroll, what is delivered, and what you can
configure and extend.
The model is also useful for other interfaces with Oracle HRMS.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 51

Payroll Interfaces
Payroll Interfaces
Payroll Integration with Oracle HR
Oracle Payroll
Vendor Partner Payroll
Payroll Interface Kit

1-44

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Payroll Interfaces and Integration Levels


Oracle Payroll: The best integration between Oracle Human Resources and a
payroll product is achieved by using Oracle Payroll. No toolkit is required.
Integration is delivered:
products share the same data and entities;
data changes by end-users are simultaneous;
the delivered products evolve simultaneously.
Vendor-partnered payroll interfaces provide another level of integration. An
Oracle team and the payroll vendors collaborate for an integrated product, based
on this same integration kit. Modifications to the kit are limited to the joint
effort; customer enhancement requests are merged, when possible. This
technique has been successfully implemented for a number of US payroll
vendors, including ADP, Ceridian, and ProBusiness.
This toolkit presents another type of integration with Oracle HR and a payroll
vendor. Configuration of the toolkit is required: analysts and developers will
customize views and ensure the payroll extract performs as required.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 52

Overview of Toolkit
Overview of Toolkit
Oracle HR: Views for Extract
Supporting code:
Trigger control
Extract verification
Sample script
Documentation: User Manual

1-45

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Payroll Interface Toolkit


The toolkit is a system involving processes on both the Oracle HR system and
the payroll system.
Delivered template views return employee, assignment, salary, and deduction
information. Other code components protect data integrity, and documentation
provides explanations, descriptions of view content, instructions and examples.
Roles
Analyst: Considerations for the analyst include:
Integrate Oracle HR and third party payroll
Third party media
System requirements
Specific data flow and transfers
Developer: Considerations for the developer include
Implementation restrictions for HR
Limitations on HR
Structure of views

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 53

Payroll Interface Toolkit


Payroll Interface Toolkit
Third Party
Payroll

HRMS Data

Validate
Correct as necessary
Extract as necessary

Interface
Views
Validation

Extract

1-46

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Flow Overview: Forward Feed


Views created from HR data are delivered as templates in the interface; you can
copy and customize these views. You then define an extract process that
retrieves data from those views. The extract should yield results that
correspond to the third party payroll.
Your extract should also validate HR data. You can make corrections in the HR
application, and repeat the extract. When you have a valid extract, data can be
moved to the external or third-party payroll system.
Payroll Interface Views
Delivered forward feed views include person, assignment, payroll, deductions,
costing, salary; the prefix is hr_pay_interface_.
The hr_pay_interface_us_eft_v demonstrates access of country specific
personal payment methods, accessing US electronic funds transfers (EFTs).
Data extract views do not use security profiles, enhancing performance.
The extract program should format data for the payroll. For example, the date
formats and field sizes may be adjusted.
Delivered keys are recommended for each table and view; all views share a
person_id key.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 54

Data Flow
Data Flow
Third Party
Payroll

Payroll
Result
Feed

Reformat

Data
Pump
Tables

Oracle
HRMS

Upload
Payroll
Upload

Forward
Feed

Extract
File

Oracle

1-47

Backfeed
Tables

APIs

Extract Template Views


Process

Custom Code

Backfeed

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Data Flow Diagram


This diagram identifies components of the Forward Feed, Backfeed, Oracle
HRMS, and the components that you customize to synchronize data between the
two systems.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 55

Overview of Data Flow


Overview of Data Flow
Third Party
Payroll

Data
Pump
Tables

Payroll
Results
Feed

APIs

Backfeed
Tables

Oracle
HRMS
Payroll Upload

Extract
Process

Template Views

?
Last_update _date

1-48

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Additional notes on the Forward Feed:


Normally you extract view data that has changed during the specified period by
defining your extract to use the _last_update_date view columns.
View data is current as of the extract date. However, you can alter the extract
date with a delivered function.
The data extract program should include validation to identify invalid data and
errors. Data errors corrected in Oracle HR will ensure data integrity and
synchronization between the two applications.
The error-free data is then written to the third party payroll application using the
upload application program interfaces (APIs) provided by the payroll vendor or
development team.
Additional notes on the Backfeed:
The Backfeed allows external payroll data to be loaded into Oracle HRMS.
Data in a fixed format is loaded by Data Pump into Backfeed tables.
Discover views and Forms are available for access and verification of the
employee elements and balances from the Backfeed tables.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 56

Backfeed
Backfeed

Data Pump and Backfeed APIs


Backfeed Tables
Backfeed Business Views
Backfeed Forms for Viewing Balances

1-49

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Additional Notes on Backfeed


Understanding and using the Third Party Payroll Backfeed requires functional
and technical knowledge of the Oracle HRMS product architecture, including:
The Oracle HRMS data model
APIs and how to call them
PL/SQL
HRMS Concurrent Process parameters
How to use and customize Data Pump.
The generic version of Oracle Third Party Payroll Backfeed can be customized
to fit the your third party payroll and HRMS implementation.
Tables, views, balances, forms, and processes specifically for the Backfeed
allow you to use Oracle Payroll and a third party payroll system. Your Oracle
Payroll implementation is not impacted by Backfeed features.
Release 11i.2+ delivers and installs the generic payroll backfeed as part of
Oracle HR. Be certain to use current information for your installation.
Backfeed tables have the prefix PER_BF_

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 57

The Backfeed data pump package, PER_BF_GEN_DATA_PUMP, contains


functions to resolve internal system IDs. Data Pump will automatically call the
appropriate Backfeed APIs. The function definitions are delivered in two
scripts; pebgendp.pkh and pebgendp.pkb.
Note: If you are using Oracle HRMS 11i they are located in
$PER_TOP/patch/115/sql.
Upload options: You can use HRDU or Meta-mapper from Data Pump.
Backfeed results can be viewed in the Find Third Party Payroll Run Employee
Results or Find Third Party Payroll Run Organization Results windows; both
have alternate regions for Payment Details and Balance Details.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 58

HR Setup Considerations
HR Setup Considerations

Employee Types
Addresses
Phones
Elements

1-50

Copyright Oracle Corporation, 2001. All rights reserved.

Setup Considerations
Analyze requirements in advance of setting up Oracle HR and your payroll
system(s).
Complete installations, resolving issues before implementing the payroll
interface kit.
Employees who will be in the extract need to have
unique employee number
a primary address using the primary address flag
in order to be included in the extract views, and for the views to function
properly.
Employee Types managed by the interface kit include:
New Hires
Current employee
Re-hired employee
Terminated employee
Assignment Status includes:
Current Assignment
Terminated Assignment
Future-dated Assignment

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 59

Payroll Status includes:


Process
Do not process
Important HRMS attribute:
ACTUAL_TERMINATION_DATE
FINAL_PROCESS_DATE
PER_ADDRESSES for address, home and work telephone numbers; the
work number entered on the Phones Form.
Notes:
If Oracle HR has already been implemented, some modifications may be
required.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 60

Setup Restrictions
Setup Restrictions

Elements
Bonuses
Working Hours
Costing
Personal Payment Methods

1-51

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Setup Considerations - continued


The Additional Element Type Details descriptive flexfield requires a
segment named Payroll Interface Flag, which must be set for elements to be
included in the extract views.
Element input values must be sequential and begin with 1 (one).
Bonuses must be created as Payroll deductions.
Deductions are created as Oracle HR Elements
Both the Backfeed and Forward Feed of the Generic Payroll Interface kit have
specific setup requirements for Payment information and Balance dimensions
and types.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 61

Interface Views
Interface Views
Employee
Special Information
Contacts

Assignment

1-52

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Interface Views
The payroll interface toolkit views have names starting
HR_PAY_INTERFACE_
For data to remain synchronized between Oracle HR and the payroll
application, primary keys must be identified. All the delivered views have a
common person_id column for ease in configuration.
For the interface template views, specific keys are recommended. Triggers
prevent users from actions that update these primary keys (triggers discussed
later).
For ease of customization: views return the first three attributes of descriptive
flex field segments for included tables, where possible.
An example script that describes how to change the extract date is pegpiexp.sql.
The package that creates utilities and sets the extract date is
pegpipkg.pkh and .pkb.
Employee views include employee information, contacts, special information,
and assignment information.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 62

Interface Views
Interface Views

Costing
Elements
Deductions
Salary Views

1-53

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Views
Separate views include assignment costing and assignment costing with G/L
accounting flexfield values.
Five element views vary by the number of input values they can each retrieve.
The naming convention is hr_pay_interface_ele_ent_1_v.
Specific instructions for numbering input values and other element setup are
described in the interface toolkit documentation.
Two interface views for salary information correspond to the salary access
methods in Oracle HR. The view hr_pay_interface_sal_admin_v uses the Salary
Administration module to retrieve only approved salary proposal details. Salary
is retrieved from PAY_ELEMENT_ENTRY_VALUES_F, avoiding a possible
end-dated approved salary proposal element entry and a value in nondatetracked PER_PAY_PROPOSALS F.
Salary information based on the Oracle HR grade module is extracted using the
view hr_pay_interface_grade_rates_v.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 63

Backfeed APIs
Backfeed APIs
Payroll Run
Payment Detail
Balance Amount

1-54

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Backfeed APIs
These APIs map between delivered Data Pump and Backfeed tables
in Oracle.
Create_Payroll_Run API: payroll name, business group, payroll name, payroll
identifier, effective date, start date, end date, and process date.
Create_Payment_Detail API: includes payroll_run_ID, payment_date,
Employee_number, amount, currency_code, check_number, check_type,
org_payment_method,
Create_balance_amount API: includes the fields employee_number, effective
dates, payroll_run_ID, currency, and balances for dimensions, including:
FYTD, MTD, PTD, QTD, Run_amount, YTD.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 64

Features for Configuring


Features for Configuring
Extract
Definable Features
Flexfields
Point in Time

1-55

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Extending and Configuring


In addition to configuring the extract and formatting the backfeed file, the
toolkit provides features that accommodate your additional business rules.
Support for Descriptive Flex Fields
Descriptive flexfield segments of all the major areas in each of the views are
available. This allows you to easily access information specific to your
implementation and transfer it to the payroll application.
Availability of Surrogate IDs
The surrogate IDs of the major tables in the views are included. This enables
you to easily join the interface views to each other and to other tables in the
Oracle HR schema with a simple where clause.
Technical Note:
Customizations may need to be reapplied when upgrading to another version of
the toolkit.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 65

Triggers and Legislative Areas


Triggers and Legislative Areas
Data that should not be changed in HR includes:
Elements, Element Reporting Name
Element Entry
Employee numbers
Personal Pay Methods

1-56

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Triggers and Interface Restrictions


Retaining extracted data in Oracle HR, especially for element entries, is critical
to proper interface behavior. The toolkit uses triggers to restrict conflicting
behavior. For example, one trigger prevents purging of element entries; other
interface trigger restrictions include imposing consistent employee numbers
(cannot be changed).
For details of grouping options and differences in R11 and R11i, please refer
Online Help: (Help) Oracle HRMS > Payroll Definition > How To >
Define Dynamic Triggers and Group Dynamic Triggers into Legislative
Functional Areas
Grouping Dynamic Triggers
You can group triggers in the Dynamic Trigger Functional Area Grouping
window, then enable or disable all triggers for the entire area simultaneously.
Functional area groupings are predefined for the interface kit. You can define
subsets; for example, if you want to create different payroll and legislative
groups.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 66

Dynamic Triggers
Dynamic Triggers
R11i.2+
Dynamic Trigger Control
Professional Interface (Form) control
Enable triggers for Generic Payroll Interface

1-57

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Dynamic Triggers
The Release 11.5 Generic Payroll Interface Toolkit (and R11i.2) uses Dynamic
Trigger Control, with a Functional Area Form from which to enable and disable
the triggers.
The triggers are delivered disabled; you need to enable the triggers in order to
utilize the Generic Payroll Interface.
For more details on the Trigger Control functionality, and how to enable and
disable the triggers, see the document entitled Dynamic Trigger Generation
available on Metalink.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 67

HR Development Interface Model


HR Development Interface Model

Outbound data: Views


Inbound data: APIs
Supportable
Not complex

1-58

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Interface Models
The model for interfacing with Oracle HR
Use APIs to move data into Oracle HRMS tables
Use HRMS views to extract data from Oracle HRMS tables.
This is the model for the Oracle Generic Payroll Interface Toolkit; this model
and toolkit is the also the framework for vendor-specific payrolls. You can use
this model for interfaces with other products or systems.
References
The Oracle Applications manuals, available online, are supplemented by the
Payroll Integration Kit manual (available on Metalink) for more information
about the integration of products.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 68

Summary
Summary
Having completed this lesson, you should be able to
do the following:
Describe Payroll Integration with Oracle HR
Discuss the Generic Payroll Interface Kit
Identify points for customization in the Payroll
Interface Kit
Locate Payroll Integration Kit References

1-59

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 69

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Interface Tools and Utilities


Chapter 8 - Page 70

ADE (Application
Data Exchange)
Chapter 9

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 1

ADE (Application Data Exchange)

ADE (Application Data Exchange)

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 2

Objectives
Objectives
After completing this unit, you should be able to do
the following:
Describe ADE (Application Data Exchange)
Identify User Types
Identify Modes of operation

Discuss ADE setup requirements


Create Styles
Upload Data

1-2

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 3

Agenda
Agenda
ADE (Application Data Exchange)
Features of the product
How ADE works

Installing ADE
Using ADE
Troubleshooting ADE

1-3

Copyright Oracle Corporation, 2001. All rights reserved.

Topics
Definition, purpose, setup, and use of ADE.
Considerations for ADE in supported Application releases
Installation
Post-installation steps
R11i ADE
Using ADE:
- Modes and Styles
- Querying, Uploading, and Letters/Mail Merge
Troubleshooting

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 4

O
e

y
l
n

The ADE Product


The ADE Product
VB (Visual Basic) add-on to HRMS
Enables you to integrate HRMS data modifications
with desktop tools
Word Processors
Spreadsheets

Export and Upload HRMS data

1-4

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ADE (Application Data Exchange) Application


ADE is an additional, optional Visual Basic application you can install on
HRMS. Only some users may need the ability to export and import data
between the HRMS application and desktop tools. Within HRMS, ADE is
available for use from only HR and OTA forms (not from Oracle Payroll).
You can use ADE to query HR data, export it to a desktop word processing or
spreadsheet application for external manipulation, then upload the changed data.
Salary Administration is a delivered example of using an HRMS API and ADE.
Letter Generation uses ADE from the Letter Requests window. You can create a
Mail Merge file from the letter Requests lists and launch a word processor.
Letter mode enables you to generate and print standard letters for Recruitment
and Training Administration. Salary change notifications is another option for
letter usage.
Additional ADE Notes
ADE windows access Views, Styles, context sensitive HTML Help.
Supported Tools include: Microsoft Excel 95 and 97, Lotus 1-2-3 v.5,
Microsoft Word 95 and 97; Discoverer can also be used with ADE.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 5

Process Overview
Process Overview
For each of the Application environments:

Launch ADE
ADE reads from generated files & parameters
ADE makes database connection
User can query, download, or upload data

1-5

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

The ADE Process


This lesson discusses ADE technical changes in these HRMS releases, to assist
you in designing setup and in troubleshooting
R11 (R11+).
ADE is accessed from the HR/OTA toolbar with an icon of an arrow pointing to
a spreadsheet. Alternatively, ADE can be launched by navigating to Special
menu > Export Data.
ADE Functionality allows you to:
Query your applications database
Preview and Export data
Manipulate and modify applications data
Upload modified data from ADE to the application
Generate standard letters
Launch tools, including:
a word processor or spreadsheet
any other program defined on your system

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 6

The ADE Environment


ADE uses styles, which specify queries. Styles reside in a file on your PC (not
on the server); a set of extensible styles is provided with ADE.
Overall process steps:
ADE is launched, either standalone or via HRMS/OTA
ADE reads from generated files and from parameters passed in to it
ADE establishes a secure connection
User in a secure session can then begin query and processing
The actual process for initiating and using ADE is the same across all platforms
and environments; but, since ADE is a PC-only application, launching ADE
varies with releases.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 7

Applications Mode

Applications Mode
ADE

ADE Data

Person Form Style


<Default>
or Folder
Style 1
Style 2
XL

Query

Excel
Database
Call API

1-6

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Applications Mode
Applications modes include
Exporting a query and format structure
Standard Forms and styles

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 8

Implementation and Environment


Implementation and Environment
Desktop Application Evolution:
10.7sc: HRMS on Desktop
10.7NCA: HRMS on Application Server

ADE must be launched


R11, R11i: HRMS on Application Server

Application can write to client

1-7

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Implementation and Environment


We identify the minor differences in implementing ADE in any of the currently
supported releases by considering how ADE implementation has changed.
For this discussion, consider that:
ADE always runs on the desktop. The HR and OTA applications resided on the
desktop in 10.7sc (smart client), moving to the Application server from
10.7NCA forward. Beginning with Release 11, HR/OTA (on the application
server )can write to ADE on the client.
Current client or desktop platforms include: Windows 95 or 98, Windows NT
3.5 or 4.0.
Note
The next 3 pages are informational, for customers who may be familiar with
previous versions. ADE components remaining from previous installs may
confuse debugging, for example, if you have multiple ade.ini files, you may not
be editing the active one.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 9

ADE in 10.7sc
ADE in 10.7sc

Client
Application

16-bit SQL*Net

HRMS
32-bit SQL*Net

Hrio.tx t

ADE

1-8

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Smart Client Reference Information


Applications run on the client in this environment, using 16-bit SQL*Net to
communicate with the database. ADE is also installed on each client (PC). In
this environment, one PC application can directly spawn another application.
(No security issues prevent the applications on a PC from spawning another
application on the same PC.)
In this environment, the user initiates ADE by pressing the toolbar ADE button.
This causes the HR application to write a file named HRIO.txt to the client
machine, the application then immediately calls the ADE executable, starting
ADE.
ADE reads the text file and parameters from the Application. Then ADE makes
a secure connection to the database: 32-bit ADE uses 32-bit SQL*Net to
establish its own connection.
After this step, ADE connections are complete: the user can then use ADE to
download and upload data.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 10

ADE in NCA
ADE in NCA
Web Applications Server
Forms Session

HRMS
Browser
Client

32-bit SQL*Net

Launcher

1-9

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

NCA (Network Computer Architecture) Environment Reference


Information
The NCA applications run on the Web Apps Server. Your PC runs a browser or
appletviewer, connecting to a Forms session, which then runs the application on
the Web Apps Server, connecting to the database.
In NCA, as always (including through R11i) ADE runs on the PC. The
application writes a file to the PC, launching ADE. Allowing a browser to write
to a PC violates security. The resolution uses the ADE Launcher to connect to
the database with 32-bit SQL*Net.
When the user presses the ADE toolbar button in the Browser, information is
sent to the Forms Session on the Web Apps Server. The equivalent of an
HRIO.txt file and parameters are written to the database: this avoids the
restriction of the NCA Web Apps Server writing directly to the client PC.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 11

ADE in NCA
ADE in NCA

Client
HRMS

Hrio.txt

32-bit SQL*Net
ADE
ADE Details

Launcher

1-10

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ADE Launcher in NCA Reference Information


The ADE Launcher continually polls the database for the ADE Event,
indicated by the ADE details on the database. The launcher uses ADE event
information to:
write the HRIO.txt file,
launch ADE, and
pass parameters to the ADE application.
Because the Launcher is already running on the client PC, there is no security
violation preventing it from writing to and spawning other applications.
In NCA, as in the Smart Client environment, ADE uses 32-bit SQL*Net to
establish its own connection to the database. From this point, ADE runs in NCA
as it does in Smart Client.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 12

ADE in R11+ Environment


ADE in R11+ Environment
Web Applications Server
Forms Session

HRMS
Client

Hrio.txt

Net8

Browser

ADE

1-11

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

R11+ Intranet Environment


R11+ and 10.7NCA share these features:
the browser runs on the client
browser communicates with Forms session on Web Apps Server
Web Apps Server communicates with the database.
The R11+ user initiates ADE by pressing the toolbar ADE button from within
the browser. The Forms session detects this event, writes the hrio.txt file to the
PC, and uses parameters to launch ADE. ADE establishes its own database
connection using 32-bit SQL*Net.
In the intranet environment, the Application can write the required file to the
client machine because the client has provided permission: a performs.jar file
provides a certification process through Java.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 13

Access ADE from the Applications


Access ADE from the Applications
Access ADE from HR and OTA (Oracle Training
Administration)
ADE Button on Toolbar far right
Special Menu -> Export Data

1-12

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Application Access of ADE


We have discussed installation for supported environments, and need to now
discuss configuration and setup components. The completed installation and
configuration enable the user to access ADE from HR and OTA using either the
toolbar icon or the Special Menu to Export Data.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 14

ADE Components
ADE Components
HRIO.txt:

Form Name
Date
Username / Responsibility
Query
Business Group ID

Parameters
Application username, password, database
GWYUID, FNDNAM

Connect to DB with Net 8

1-13

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ADE Components
Generated ADE files include HRIO.txt, which contains details such as:
the name of the form which called ADE; this is required to determine the
styles which you make available during setup
the date
username and responsibility
the last query performed by the form; you can choose to enable the user to
recreate the last query by providing the function
the business group ID.
Parameters: ADE requires parameters, generally, they include the application
username, password and database which to connect to the GWYUID and
FNDNAM. These parameters are required to establish a secure connection to
the database and fulfill Oracle application security restrictions.
Connection: ADE always uses 32-bit SQL*Net connections, which must be
configured on the client.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 15

ADE Modes
ADE Modes
3 Modes of Access and Operation
Standalone Launch from Desktop
Applications Launch from Toolbar Icon
Letter Generation / Mail Merge

1-14

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ADE Modes
The user task to perform dictates which of three modes is used:
Standalone. ADE is invoked from your PC desktop and run independently,
without accessing either HRMS or OTA. To run ADE standalone, launch ADE
from the desktop, then log in with your Application username and password.
You then choose a responsibility, as you do in the applications; this allows ADE
to make a secure connection to the database. Once connected, you can query,
export, and upload data.
Application. Invoke ADE from the application toolbar button to run within
HRMS and OTA. Using ADE in application mode, you can:
launch another application directly (without transferring data to the
application) and run it separately from your application.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 16

transfer data from your database to the built-in ADE spreadsheet, then either
launch a word processor or spreadsheet application to perform a mail merge or
you can analyze the data. You may launch such applications as:
- a spreadsheet program, such as Microsoft Excel
- a word processor, such as Lotus Notes or Microsoft Word
- Discoverer
- SQL*Plus, or
- a third party program.
Letter request and Mail Merge.
In the Application: Invoke ADE from the Merge button in the Request Letter
window in Oracle HRMS or Oracle Training Administration when you want to
use HR data to produce standard letters for recruitment or enrollment.
In Standalone or Application mode, you can export the queried data, then
launch Microsoft Word to run the Mail Merge.
Technical Note
Note that Styles correspond to these modes; discussed later in this lesson.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 17

Installing ADE - Prerequisites


Installing ADE - Prerequisites
Net8 installed and configured
Application SID
Test Connections with SQL*Plus

Check Patchsets and Installation Instructions

1-15

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ADE Installation Prerequisites


The primary prerequisite for ADE installation is Net8, a 32-bit SQL*Net, with a
32-bit Oracle Home on your PC. Installing ADE includes configuring the
TNSNAMES.ORA for Net8 located under your Network\Admin directory
within the ORACLE_HOME.
When you download the ADE patch, all required components are included.
Note that: R11i uses Net8; R11 uses SQL*Net 2.3.
SQL*Net should be configured accurately.
ADE from the applications requires a TNS entry for the application SID.
Omitting this is a frequent source of error. Confirm your connection by testing
with SQL*Plus after manually editing the TNSNAMES.ORA file. Ensure that
you can connect from your client, before assuming ADE can connect.
Post-Installation by Release
There are specific post-installation steps for each supported release. Be certain
to check Metalink for complete and current instructions.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 18

Basic ADE Setup Steps


Basic ADE Setup Steps

Run install shield: Register ADE


Complete ade.ini definition
Define paths
Set miscellaneous options
Define menus
Enable default queries

1-16

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Overview of ADE Setup: Checklist


This checklist provides a summary of the System Administration setup steps.
Refer to detailed setup steps in Online Help for an explanation of each setup.
Install ADE on Desktop - for ADE access in standalone mode, and to enable
you to complete the setup procedures for ADE; the install process creates an
icon on the desktop. This is required for each PC to run ADE.
Define Paths - define paths to specify the location of the spreadsheet
application, Microsoft Word and other programs used by ADE, as well as paths
for ADE executables. This step is required on each PC.
Set Miscellaneous Options - these settings configure ADE, including:
the maximum number of records that can be downloaded to a spreadsheet.
the update mode that specifies whether data can be uploaded.
the AOL Gateway name details
the AOL Foundation details.
Create Views Views and Styles are created by the System Administrator.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 19

ADE Installation Process


ADE Installation Process
InstallShield Wizard:
Installs ADE files in C:\Program Files\ADE
Writes Library files to Windows System
Writes and Registers Oracle files to ADE\Oracle
Existing ADE files to ADE\Backups
Icon added to Program menu
Program paths added to ADE.ini

1-17

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Installing ADE
InstallShield (not Oracle Installer) installs ADE: begin install by running
Setup.exe from the ADE setup media. You can override the default location ,
C:\Program Files\ADE.
All required VB libraries are written to the appropriate windows directory.
Note: In R11i, Oracle Object files are moved to the Windows System directory,
not to the ADE/Oracle subdirectory (as in earlier releases); the path is modified
correspondingly. The installer finds and backs up any ADE.ini file that might
remain from a previous ADE installation. The ADE.ini includes style
identification.
An icon is added to the Program menu, used for launching ADE standalone.
Setup detects standard word processor and spreadsheet packages, and adds them
to the ADE setup. It may also adds an /e or /n to the end of the name in the
path you need to remove that.
These steps complete the install: ADE is almost ready to use standalone.
In NCA environments, you may need to enter GWYUID, FNDNAM, and
LOCAL values in ADE.ini, for an initial ADE connection to the database. If so,
manual edits to ADE.ini must be corrected using OVERRIDE mode.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 20

Define Options
Define Options
System Administrator: Options
Paths for Desktop Utilities
Word Processor
Spreadsheet
Letters

Miscellaneous Options
Vendor for Mailmerge
Maximum Rows in Transfers

1-18

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

System Administration Tasks


Define Paths
Log in to the Applications Data Export window as sysadmin.
Select the Options button to display the Options window.
Set up paths and directories for Temporary (hrio file) use, Queries and
Letters, and the desktop applications.
In the lower area of the form insert the paths to your word processor, your
spreadsheet, your Web browser and any other software that you may use for
import/export and processing of data.
When you select the Misc tab in the options window, a window displays
allowing you to identify desktop tools. You can set up the maximum number of
rows that you wish to import or export at any one time. You can also set the
AOL Gateway and the AOL FNDNAM.
The last task a System Administrator may complete (before turning the system
over to the end-user) is editing the ade.ini file (if required), then running HRIO
in override to revalidate the check digit routine.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 21

System Administration Options


System Administration Options
Additional Options defined by SYSADMIN include:
Database connection information
View prefixes

1-19

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

System Administration
Database Connection
If there are no database details in other INI files, ADE initially connects using
GWYUID and FNDNAM and LOCAL specified in the Options tab. This
occurs in R11 setup, requiring initial definition after the installation. The user
can override these values on the command line.
Views
Another System Administration task is to define the views for ADE users to
query, including prefixes for ADE to recognize. By default, ADE recognizes
views with the prefix HRV_. SYSADMIN user can add to this default.
The ADE Views button directs ADE to write out SQL to create a view, based
on a query just performed. This function is enabled by including the function
HRIO_Enable_Views in a menu.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 22

Identify Tools
Identify Tools
Configure to retrieve and export needed information
Install a spreadsheet application
Install a word processing application for mail
merges

1-20

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 23

HRIO Functions in Menu


HRIO Functions in Menu
Add HRIO Functions to Menu for User

Enable Options System Administrator


Enable Default Query non-folder windows
Enable Upload usually limited
Enable Views Data Preview window
Enable Styles custom views

1-21

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Define Menus
ADE function access is controlled by the user responsibility at login to ADE or
the application. Identify these functions in the appropriate menu.
HRIO Enable Options allows access to ADE sysadmin options, such as
changing path or the database connection. These Sys Admin functions are
normally performed by the installer. A user with access to this function will be
directed to the Options window at login, whether in Standalone or Applications
mode, precluding standalone mode as an ADE end-user.
Note: If a user in Applications mode sees only the Options window, it is
because the function is included on a menu or submenu associated with the
responsibility. This can be resolved by excluding the function from the specific
user or responsibility.
The remaining HRIO functions impact users accessing ADE from the
HRMS/OTA Applications.
HRIO Default Query allows a user to perform the last query performed by the
Application, which is usually the last query performed by the Form from which
ADE is launched.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 24

HRIO Enable Upload permits a user to select the Upload button on the Fetch
Data window, to upload modified applications data which has been exported
from ADE.
HRIO Enable Styles enables a user to choose a button that pulls data from the
Data Preview window, creating a new style from that data.
HRIO Enable Views enables a user to pull data from the Data Preview window,
creating a new view. The enabled button initiates the function requesting ADE
to create a SQL view definition, based on the Form SQL. The resulting view
can be used in ADE Standalone or by a data query tool.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 25

Setup Checklist
Setup Checklist
Standalone Mode Setup:
Create Views
Create Styles

Application Mode Setup:


Create Styles

1-22

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Styles, Views, and APIs


Styles are the key ADE component to define and use: understanding Styles
simplifies using ADE. We will discuss the types of styles and where they are
available in the following sections.
A Style in ADE defines the following:
the data queried by ADE: identifying data columns to fetch into the
spreadsheet
data uploaded by ADE: identifying what data is uploaded into the database,
by which API
for mail merges: what data is fetched, and moved into what document.
Defining Styles is simplified by using the Enable Styles function: this function
allows you to first perform a query, then the function results in ADE creating a
style based on that query. This removes the need to define all associated
columns for an ADE Style.
In addition to defining styles, you may define scripts for API uploading.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 26

Setup Checklist Letter Generation


Setup Checklist Letter Generation

Define Letter Types


Create Views
Create Styles
Set Up Mail Merge Documents

1-23

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Mail Merge and ADE Modes


Letter Request Mode from the Request Letter window in Oracle HRMS or
OTA: automatically generate recruitment and enrollment standard letters.
Standalone Mode query to export data directly from the HRMS database.
Application Mode by querying data for export from an application window
Setup tasks:
Define Letter Types for recruitment or enrollment letters to be generated
depending upon assignment or enrollment status; create the Mail Merge
document.
Create the views to retrieve data for standard recruitment or enrollment letter
requests. Certain HRV views are delivered.
Create Styles for generating letters from the Request Letter window. Define the
Styles for letters as a LETTER style, include:
the name of the view created to retrieve the data
the name of the letter defined as the Letter Type
the name of the mail merge document.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 27

Key ADE Files


Key ADE Files
Generating
HRIO.dbg
HRIO.sql
HRIO.api files

ADE.ini
HRIO.txt
HRIO.qry
HRIO.xls

1-24

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HRIO files
Note that ADE prefix HRIO is used for default filenames. You can save queries
and data by renaming the HRIO files; otherwise, subsequent ADE actions will
overwrite the HRIO files.
HRIO.qry saved query file
HRIO.xls temporary .xls
Mail Merge files are standard Word documents. One is created for each
standard letter or report you want to generate using ADE. The document
contains the letter text and fields to merge the data.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 28

Using ADE
Using ADE
2 distinct users:
privileged user (SYSADMIN)
normal user

3 main uses:
querying data
uploading data
performing a mail merge

3 modes of operation

1-25

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ADE: Users, Usage, Modes


There are two primary ADE User types. The privileged user is the System
Administrator, who defines options, such as paths and default directories. The
SYSADMIN user can also create styles and define views. This user can run
ADE with the OVERRIDE option, required to validate the ADE.ini file and
correct the checksum after manual edits.
ADE also has an end-user. This user performs queries, downloads data from the
application, and so forth. You can grant this user additional functions.
Examples of ADE modes follow. In summary, recall that:
Standalone mode: by definition, the user does not need to run Applications;
ADE connects directly to the database, enabling options, queries, and uploads.
Application mode involves launching ADE from the Application, assuming the
same username and responsibility for ADE and the Application. This mode
enables the user to perform queries, extract to desktop applications, or to upload
data, as well to run other applications such as Discoverer.
Letter Request mode is launched from PERWSRQL, the Letter Request Form;
ADE logs in to the database, queries data, and performs a mail merge.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 29

ADE Security
ADE Security

Application Security: Responsibility


Styles associated with Responsibility
Query: Mail Merge or Letter
Standalone: restrict Upload

1-26

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Security and Control


ADE uses the HRMS and OTA security model: responsibilities restrict access to
the data from the applications database, and provide other features to control
data access to the view retrieved by database queries.
You can define and limit each style for a specific responsibility, limiting styles
to users. Another constraint is provided by the style definition for usage. For
example, a letter style is defined to be used for mail merge.
Defining Styles for ADE Standalone allows you to specify whether exported
data can be edited and modified data uploaded back to the database.
Technical Notes
Under the Options > Views tab, you can add prefixes to allow ADE to
recognize other views, such as your custom views.
Identify the API: If your style enables data upload, you must identify the API;
optionally, you can create an API PL/SQL script for the data.
Standalone Query Style: Your standalone query style must be defined as a
GENERAL style and must include the name of the base view.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 30

Manage Styles
Manage Styles
Use the Styles page to:
Create a new style
Delete a style
Modify a style

1-27

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Styles and Columns


Styles and the Style Columns are defined by the Sysadmin user. You can create
styles to define a set of queries that can be performed using ADE in application
mode, also create styles and server views to define a set of standalone queries to
retrieve data from the database.
Create Views - Views installed on the server are used to retrieve data for
standalone queries. A number of HRV views are supplied on the database.
Others can be found in a script that is delivered as part of the client-side install.
Your Database Administrator can customize this script to create additional
views, which must then be installed on the server.
Create Styles (Standalone Mode) - A style for a standalone query must; be
defined as a GENERAL style and include the name of the view created on the
server to retrieve the data.
Create Styles (Application Mode) - Styles defined for queries using ADE in
application mode must include the name of the Form used to return data for the
query.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 31

ADE Styles
ADE Styles
Styles define Data for Query and Upload
GENERAL: Available in Standalone
FORM: Associate with particular HRMS Form
LETTER: Associate Document with letter/mail merge

1-28

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Manage ADE Styles


You can define four types of style for data exchange using ADE:
GENERAL: Exports data directly from the database using ADE in standalone
mode.
FORM: Exports a set of records or a single record from a window. You specify
the Form name; when executed, data is retrieved by the view used for the
application window. These styles are available in Application mode.
LETTER: Exports data to perform a mail merge for generating standard letters
for recruitment and enrollment, using ADE in letter request mode.
UPLOAD style: Allows updates to information that has already been
downloaded in ADE. The user chooses whether to correct or update, as
DateTrack options.
Depending on the type of style and data usage, you also define:

The view used to retrieve the data

An API for uploading modified data

A WP document for performing a mail merge

A letter type associated with recruitment or enrollment statuses.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 32

Create Styles
Create Styles
Modes of Operation correspond to Styles
Associate Style with
Responsibility
Form, View, Letter / Document
Upload API

Define Columns
Field, Name, Display Width, Data Type
Update Options

1-29

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Style Definition Screen


Select from the values for List of Styles. For each style, define:
Style Name
a Responsibility that will access the Style
a Form to associate with the style, if it is to be accessed from the
Applications; otherwise, in place of the Form name, use GENERAL for
Standalone or LETTER for Letters/Mail Merge.
A view upon which to base the style. This field is required for GENERAL
queries. Note that if you enter a view for a Style based upon a Form, ADE
will query against the view, not against the base tables behind the default
query.
Letter Name, Document - required only for Mail merges. The Letter Name
corresponds to the letter name as used in the Application. Note: use
underscores rather than spaces in the letter name; this avoids confusion in
interpretation of ADE parameters.
Upload API is the API script procedure you defined.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 33

Style Columns
You can select Default to enter all the columns available for a particular style.
You can then modify the column information to suit your needs.
In the Style Columns tab, for a given style, you enter:
Field Name the label to appear in your spreadsheet.
Column Name - the name of the queried data column from the view or from the
Form base table.
Column attributes include Width, Upd? (Upload), General (Display/Update
characteristics), and Datatype.
W represents the width of the field on the Spreadsheet.
Upd? is the Upload option
0 = Displayed in Spreadsheet, non updateable, not an API parameter
1 = Displayed in Spreadsheet, updateable and an API parameter
2 = Not displayed in Spreadsheet, and is an API OUT parameter
3 = Not displayed in Spreadsheet, an API IN/OUT or OUT parameter
4 = DT parameter to API
General (Note that the meanings of these values differ between GENERAL and
Upload Styles)
0 = Field displayed, but not updateable
1 = Field displayed & updateable
2 = Field not displayed
Type (Datatype)
V = Varchar2
N = Numeric
D = Date
Lookup Type: name of the view that returns a list of values

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 34

ADE Queries
ADE Queries
Query in Standalone or Application mode
User can restrict query in each mode

Select Style as Query basis

1-30

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Restricting the Query


Standalone: You can restrict the query as you build it in standalone mode.
In Application Mode: ADE will use the WHERE clause as specified in the
Application Form query. For example, you can limit the query (query by
example) on the application, using ADE to perform the same query.
Optionally, you can define a Style to override the FROM clause, and select
from a different view. However, ADE will always append the WHERE clause
used in the Form.
Note of caution: when overriding the view, be certain that columns in the
WHERE clause (which you cannot override) are also contained in your
overriding view.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 35

Define Query
Define Query
Define Query Screen
Define Queries
Query in Standalone

Query Details identifies available Styles


Criteria identifies columns user selects columns
and relations to compose query

1-31

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Define Query screen


We use this screen to query in Standalone mode. Query Details displays
available styles; Criteria displays the associated columns.
You can drag the Criteria columns onto the sheet to build a query on the view
for the selected Style.
Moving a field below another builds an AND clause;
Moving a field onto the same line next to another field builds an OR
clause.
Fetch performs the query, returning values to the Data Selection screen.
Load allows you to load previously saved queries.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 36

Querying Data
Querying Data
Application Mode
Fetch Data window
Form name
Start query execution

User selects Style


Fetch fetches columns
Start fetches columns into Application, when
possible

1-32

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Fetch Data Screen


We use this screen to query In Application mode. The Form name used to
launch ADE is visible. The user selects a Style from the list of Styles.
Fetch: fetches columns associated with that Style using the WHERE
clause from the application, thereby including application security
constraints.
Start: fetches columns into the application, where possible.
Other applications can be launched
Note: When the query is performed, values are returned to the Data Selection
screen. When a default query is executed, all the columns queried by the
Application Form are returned; in Standalone mode, only the columns specified
by the Style are returned.
Style creates a style based on these columns. This is useful for creating a
default query, which you can then edit, limiting columns.
View creates a view based on this query.
Sheet outputs the data to the spreadsheet
Word use this button if you have an associated document for mail merge.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 37

Launching ADE Standalone


Launching ADE Standalone
Application Sign-on
Application Security: Select Responsibility

1-33

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Launching ADE in Standalone Mode


Enter your application user and password in the Oracle Applications sign-on
window displayed when you start ADE in standalone mode. Database access
uses applications security, as defined by the System Administrator.
The Oracle Applications Sign-on window also includes an Options button, if the
Enable_Options function is available. Normally the System Administrator uses
this function; however, an end-user with access to this function may use it to
change paths, corresponding to specific PC tools.
Selecting a Responsibility: If more than one responsibility is available, the
Responsibility window is presented when you use ADE in standalone mode.
Exporting Data in Standalone Mode
You can perform a query by simply selecting a query from the Define Query
window and invoking the query for a default transfer of all fields. You can
define query conditions to further limit the selection and format of data; or use
the arrow on the order field to specify the order of queried data.
The Fetch button exports data to the built-in ADE spreadsheet Data Preview
window. You can also use buttons to save the query to use at a later date, re-run
the query, or delete a saved query.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 38

Upload Data
Some ADE queries will allow you to modify applications data in ADE and then
upload the modified data to your applications database. The sequence of highlevel steps is:
1 Perform a query on your applications data
2 Save the spreadsheet.
3 Edit the data in Excel.
4 Upload the modified data.
For more information, please refer to the Online Help path:
(Help) Oracle HRMS > ADE (Application Data Exchange) > Setup ADE >
How to > (link) Additional Setup > Create Styles for Upload
For example, the Salary Administration query style will allow you to download
salary proposal detail, change the data, then upload the changes.
Note: Using the Salary Administration Window is covered in the Salary
Administration course.
Instructor Note:
Inform the students that the first level in the Online Help path, which starts with
Oracle HRMS, should be substituted with their local Oracle HRMS menu tree
path level.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 39

ADE from Application Mode


ADE from Application Mode
Toolbar Icon
ADE Fetch Data window:
Select Style
Start Program to Launch another Application
Note: Uses Oracle ID Secure User

1-34

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Application Mode
To query and export data from an application window
Query an application window to retrieve data record(s).
Launch ADE from the application toolbar.
In the ADE Fetch window, select a style from the list by the window name.
The Fetch button transfers data to the Data Preview window.
The Start button fetches, transfers data and directly launches your word
processor or spreadsheet application. ADE is iconized while the program runs.
From the Start Program options, select an action:
None (refers to another application) only transfer data to the built-in ADE
spreadsheet.
Word Processor - launch word processor to perform a mail merge.
Spreadsheet - launch spreadsheet application to analyze or report on the
data.
Note: When you run an Oracle program, you are connected using the same
secure user Oracle ID you used to access Oracle HRMS or OTA.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 40

ADE Uploads: Modify Data


ADE Uploads: Modify Data

Upload Function in User Menu


Associate API with Style
Use Style to Query Data
Data exported to Spreadsheet
User can Modify Data (Spreadsheet)
Upload from Spreadsheet into Application (ADE)

1-35

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Uploads: Modify Application Data


The HRIO Upload function on the user responsibility menu enables this feature.
The process is initiated by the following steps:
In the Application form, a user launches ADE, querying data using a Style to
which an API is associated
or
Use the Define Query window in Standalone mode to perform a query and
transfer the required data to the Data Review window.
Select a Style from the Fetch window, and choose the Spreadsheet option, then
press Start.
Note that some data columns have a gray background: this indicates that the
data should not be changed. Any changes will be ignored during upload.
The data can be modified in the Spreadsheet. ADE writes all necessary
information to HRIO.xls.
The Spreadsheet is loaded back into ADE, which identifies any data changes
that have been made.
ADE generates a call to the associated API, executing the API which performs
validation (including Object Version Number as part of the HRMS API
Strategy) and loads the data back into the Application.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 41

Uploading Queried Data


In standalone mode: choose the upload icon on the desktop, or Run HRIO.exe
enabling UPLOAD from the command line (Start > Run) and specify:
HRIO.exe UPLOAD. Logon with your username and password, then select a
responsibility. The Data Upload window is displayed.
In application mode: choose the Data Upload button; this displays the Data
Upload window.
To complete the upload:
Choose the Load button.
Select the file HRIO.XLS in C:\TEMP. (Recall that extracts use this temporary
name; you can copy or rename your extracted data files.)
Load the spreadsheet.
Select a date to identify the effective date for the upload.
Select a DateTrack mode, such as: Correction, Update or Insert/Update.
Choose the Upload button. ADE uploads each row in sequence.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 42

Letter Request Mode


Letter Request Mode
Letter Request Form (HR/OTA) Launch Letter
Mode
ADE uses Style
Query Data
Write to Spreadsheet
Launch Word document

1-36

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Letter Request
Letter Request mode is launched by selecting the ADE icon in the PERWSRQL
form in HR or OTA. Select a letter request in the form: it is queried, then
parameters (including the style) specifying the letter request are passed to ADE
as ADE is launched. ADE then launches Word, and you can perform the mail
merge.
Letter request mode can generate standard letters for recruitment and
enrollment.
You can also use ADE in standalone mode and application mode to generate
other standard letters.
ADE retrieves data and exports it to a data file that is merged with a standard
word processing document, which contains all the required merge fields and the
standard letter text.
Note: Oracle HRMS and OTA provide other methods for generating standard
letters and reports using a mail merge, which do not require ADE to be installed
on the PC.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 43

Letter Request Setup


Letter Request Setup
Define a letter type
Define views
Create a letter style
Create Word document

Mail Merge Prerequisites


Define a letter type for the letter request
Define a view to retrieve data for the merge
Create a LETTER style for the letter

1-37

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Letter Setup and Mail Merge


Details for standard letter setup and the process for mail merge follow:
Define a letter type for each standard letter you want to generate. Each letter
type associates a standard letter with one or more assignment or enrollment
statuses.
Define views to retrieve data for each standard letter. A number of HRV views
are supplied on the database. Your Database Administrator can customize these
scripts to create additional views, if you require.
Create a LETTER style for each standard letter, to define the data columns used
to hold the data for the mail merge, and other parameters to retrieve data and
perform the merge
Note: Remember to include the name of the Microsoft Word document you plan
to define, for each style you create.
Create Word documents to merge the data to generate the letters.
Select or define a Style, defining the query data and the format for data export,
as well as parameters required to process the extracted data.
Access the Styles page using the SYSADMIN username and responsibility.
We have previously discussed the 4 types of styles available for export. You
need a LETTER Style to perform a mail merge for generating standard letters
for recruitment and enrollment, using ADE in letter request mode.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 44

A LETTER Style requires the name of a view and the name of the Letter. You
can select the Multiple Rows box if required.
Select the Save Changes button to save the style, then define data columns from
the Style Columns page in the Options window in Standalone mode.
You can access details to modify a column: double-click the cell to activate the
Edit Cell window.
You can insert or delete columns by selecting the row and choosing the Paste or
Cut button.
Save or Undo your changes before using the Back button.
Mail Merge
Use Word mail merge facilities to merge ADE-exported data to generate
standard letters:
Start ADE in standalone mode and log in as System Administrator.
On the Paths page, select the Test button to display the Select Style window,
then select the style to be used to export data from the mail merge.
Select OK to confirm and start Word. Word opens a document called
HRIO.RTF, which contains mail merge fields.
Enter or edit the letter text, and rearrange the merge fields in the document.
Save the finished mail merge Word document in the Letters directory.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 45

Using ADE - ADE.ini file


Using ADE - ADE.ini file
Contains all settings and style details
Should not be manually edited in normal
circumstances
Manual edits detected through checksum error
Checksum can be corrected in OVERRIDE mode
run hrio.exe OVERRIDE and log in as SYSADMIN

Can be shared across a network


set HRIO_ADEDIR in Environment settings or
Autoexec.bat

1-38

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

ADE.ini
We have discussed ADE Styles and settings. All these definitions are saved in
the file named ADE.ini. This file is installed with ADE, and initially contains
default styles and definitions.
When you create or edit a style or settings, the changes are recorded in the
ADE.ini file. This file features a checksum to validate against manual edits.
ADE will not start if this file is not validated and correct. However, there are
cases in which you might need to edit the file.
Previous ADE setup on a PC may exist. ADE.ini will override those settings.
For this reason, it is critical to completely download ADE when installing.
Complete and current installation precludes many issues.
To verify login and complete connection to the database, the values for
GWYUID, FNDNAM and LOCAL are set in ADE.ini.
Validate Checksum in Override
If you manually edit ADE.ini, such as you might at installation, you must verify
it by running ADE in OVERRIDE. From the command line, enter:
HRIO.exe OVERRIDE.
Next, login as SYSADMIN to access and exit the Options screen. This action
corrects the checksum. From this point, users can log in to ADE normally
(without OVERRIDE).

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 46

Sharing ADE.ini
The ADE.ini can be shared over a network to avoid manual edits on multiple
PCs. The process is platform-specific:
On Windows NT, use Settings > Control Panel > System > Environment to
create the variable HRIO_ADEDIR and define the path for the shared ini. On
Windows95, use the Autoexec.bat file.
Reboot your machine after changing this definition.
To Define Paths or Path changes in ADE:
Log in to ADE using SYSADMIN in Standalone.
Select the Options button.
In the lower area of the Options window, insert or change any software
paths for ADE import/export and processing of data.
Technical Note - Citrix Reference:
Citrix installations require special handling of ADE.ini. ADE attempts to locate
the ADE.ini on a Windows or WinNT directory, so you must specify a
directory, such as C:\Program Files\ade, then copy the ADE.ini to the directory
of your choice, such as C:\winframe. You then set the environment variable
HRIO_ADEDIR to point to the actual directory, for example: set
HRIO_ADEDIR=C:\winframe
You need to define a C:\temp directory on the server, to handle ADE hardcoded
calls.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 47

Using ADE - Menu Functions


Using ADE - Menu Functions
HR_HRIO_ Menu Functions
Defined in AOL Define Function Form
Add to Menu for a given Responsibility

1-39

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Using Menu Functions


System Administrators managing Functions for ADE need to be aware of:
ENABLE_OPTIONS: A user with access to this function is directed to the same
Options window the SYSADMIN user accesses. This function provides access
to create and modify Styles.
DEFAULT_QUERY: This permits a query that has been performed by an
application form to be used by ADE in Application mode. It is useful to identify
form fields and sources; you can define styles based on this query.
ENABLE_UPLOAD: allows a user to perform uploads.
ENABLE_STYLES: allows a user to create a Style based upon the current
query performed by ADE. This is written to the ADE.ini file. If this is used in
Application mode, the user must have permission to write to ADE.ini.
ENABLE_VIEWS: enables a user to generate the DML required to create a
view, based on the current query last performed by ADE.
To grant use of a function, add the function to the default menu for a specific
responsibility. You can also exclude certain functions on a responsibility if
required.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 48

Troubleshooting ADE
Troubleshooting ADE
3 primary types of problems
Installation: a user cannot run ADE at all on PC
Application: user cannot launch ADE from the
Application
Behavior: user believes behavior is incorrect

Follow guidelines to resolve problems

1-40

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Troubleshooting ADE
This discussion is aimed at assisting you in resolving or identifying problems
that you may encounter.
Generally, the problems encountered with ADE fit into 3 categories:
Installation problems symptom: ADE will not run standalone
Application problems symptom:ADE will not run in Applications mode
ADE problems symptom: ADE behavior not as expected.
Some symptoms may be related to another type of problem, such as installation
or setup.
Other references for ADE include context-sensitive Help in HTML and the
Using Application Data Exchange manual.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 49

Troubleshooting: Installation Problems


Troubleshooting:
Installation Problems

Configure 32-bit SQL*Net properly


Path and directions
Complete ADE.ini file
For run-time errors:
Run Install Completely
Alternative installations
Identify unique PC setup

1-41

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Installation Problems
Verify 32-bit SQL*Net is installed and configured properly: all SIDs must
match those used by the Application. Test this feature by connecting with
32-bit SQL*Plus if possible, using passwords such as GWYUID, and secure
logon.
Confirm that the Path variable is set correctly.
- C:\Program Files\ADE;C:\Program Files\ADE\Oracle
- All directories in Path variable are complete with appropriate drive
letters
Note: Access is platform dependent, for example: in Windows95 check
the Autoexec.bat; in Windows NT access the Control Panel > System >
Environment.
Confirm that GWYUID, FNDNAM, and LOCAL are all defined and
correct, and that INI file has been verified. ADE looks at Windows or
WinNT directory, but you may have multiple copies: correct the versions
you are using.
For run-time errors: if any DLL registration errors occurred during
installation of ADE, test an alternate installation, such as using
Launcher.zip, which registers DLLs correctly.
Identify unusual PC configuration or options before contacting Oracle
Support.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 50

Troubleshooting: Application Problems


Troubleshooting: Application Problems
Verify post-install setup for specific environment
Verify Patchset Prerequisites
Correct Form and Library Versions

1-42

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Application Problems
Installation and setup is primary to success: Application mode ADE requires
supported files, which are provided in the post-installation steps specific to each
environment. Be certain to follow complete, current instructions.
This checklist includes Prerequisites:
Patchsets, which may include:
Current Form versions and Libraries (R11)
FRM-99999 Errors
This is not normally an R11i problem: FRM-99999 error is a generic error
message with Appletviewers. Common causes:
Form or Library not built correctly; these must be generated in the
corresponding environment. For example, a form or library generated on NT
will not work on Unix. Using the appropriate Patch resolves this problem.
For R11: Verify that you have the latest performs.jar file (not an issue in R11i),
and that it is referenced in HTML. This is associated with a security issue when
examining FRM-99999 details.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 51

Troubleshooting: Behavior Problems


Troubleshooting: Behavior Problems
Confirm Latest Version of hriomain
Verify setup and usage with Online Documentation
Attempt to solve the problem

1-43

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Behavior Problems
These two items often resolve issues:
Has the newest executable been downloaded?
Confirm your understanding of expected ADE behavior by checking against the
Online Help.
If the problem persists, you can assist by investigating further, beginning with
the following troubleshooting tips.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 52

Troubleshooting Tools
Troubleshooting Tools
HRIO_TRACE variable
Debug Files
HRIO.dbg: ADE actions
HRIO.sql: SQL executed by ADE
HRIO.api: API calls made by ADE

1-44

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Troubleshooting Tips
To debug ADE, you can enable Trace, adapting these Windows NT commands:
From the Desktop Control Panel: Navigate to >System->Environment, set
variable HRIO_TRACE with value ON, or
in Autoexec.bat, set HRIO_TRACE=ON.
HRIO_TRACE writes files to C:\Temp
Examine ADE output:
HRIO.dbg is most useful; it lists all ADE actions, stepping through details
up until the point where ADE erred.
HRIO.sql contains any SQL ADE has executed.
HRIO.api contains any API calls ADE made.
If you have errors in the latter two cases, try to run the API or SQL in a
SQL*Plus session. This may indicate exactly in which table, column, or call the
error occurs.
When ADE is launched in applications mode, it writes information to a file
called HR10.TXT in the C:\ Temp directory of the machine which runs Forms.
HR10.QRY initially stores the query in a temporary directory. If the query is
saved, the file is transferred to the queries directory and saved with a filename
of the form NNNNNNNNN.QRY, where N represents a number derived from
the date and timestamp for the file.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 53

ADE Download on Metalink


ADE can be downloaded from Metalink at the following URLs:
R11i:
http://metalink.oracle.com/metalink/plsql/dis_download.
confirm?p_id=6021.999
R10.7/R11:
http://metalink.oracle.com/metalink/plsql/dis_download. confirm?p_id=24282

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 54

Practice: Using ADE Features


Practice: Using ADE Features
Follow the demonstration or notes provided to:
Create a Style based on a view
Fetch Data using your Style

Create an Style for Uploading Data


Define PL/SQL to call an API
Associate the API with your Style
Test the Data Upload

1-45

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 55

Summary
Summary
Having completed this unit, you should be able to:
Identify ADE functions, modes, and users
Discuss the setup steps for ADE
Generate Standard Letters using ADE
Define a Style in ADE
Identify how to Upload Data

1-46

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

ADE (Application Data Exchange)


Chapter 9 - Page 56

HRMS Interfaces: APIs and


Data Pump Demos and
Practices

y
l
n

Chapter 10

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 1

Practice: Calling HRMS Business Process APIs


Part 1: Locate and call API code
The objective of this demonstration and practice is to allow you to locate and examine HRMS
API packages, and to create a user script to call an API to create an employee.
Given a scenario that you need to convert data from a legacy system, you want to
programmatically enter employee data into a configured Oracle HRMS system.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 2

Instructor Demonstration Solution: Locating HRMS API code


Part 1: Locating HRMS API code
You can find source code for the create_employee API by searching install and upgrade files on
the application server, or look at the source code in your database instance.
Search Through Install / Upgrade Files on Application Server
1. Navigate to the $PER_TOP directory and look in the install, sql and patch subdirectories. Find the .sql, .pkh and .pkb files that are used to install and upgrade the
application. Use 'grep' to search through these files for the 'create_employee' package.
For example
grep -i "create_employee" *.pkh
2. Search Through the Source Code Installed on the Database
The following SQL statements must be run within the APPS SQL*Plus schema.
Whenever a package is created on the database the uncompiled source code is stored in the
USER_SOURCE table. Search this table to find the file name of the create_employee procedure.
For example:
select distinct name
from user_source
where upper(text) like '%CREATE_EMPLOYEE%'
and type = 'PACKAGE';

I
A

y
l
n

O
e

s
U

When you have packages that contain your search string, create_employee, look for the
$header$ line in the source text. The file used to create the package is identified in the $header$,
usually within the first lines of the package.
3.

List the source code:

&
l
a

n
r
te

Having found possible package names, you can list off the source code for the package by
running the following SQL:
select text
from user_source
where name =
'<package name from previous select>';

n
I
e

l
c
a

r
O

You can also look in the USER_OBJECTS table and search for the procedure name. For
example:
select object_name
Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 3

from user_objects
where object_name like '%CREATE_EMPLOYEE%';
Examine the API package.
The create_employee procedure is part of the hr_employee_api package; the source files are
peempapi.pkh and peempapi.pkb. Ensure that you are using a publicly callable business process
API.
Entering employees for conversion or using APIs as an alternative interface depends on HRMS
configuration, including organizations and lookups such as person type. Examine the API
parameters and identify required values.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 4

Practice: Calling an HRMS API


Create a User Script to call the Create Employee API
1. Using SQL*Plus, you can spool the API and begin coding a call to the procedure.
Alternatively, you can use the file provided by your instructor to create a package body
and header that calls the API.
Note: Be sure to identify your solution by
using your unique team number in place of xx in the files or listed solutions.
2. Verify that your solution resolves required parameters, such as organization_ID,
person_type_ID, and that the lookup codes, such as for title, are correct. The fields you
write to populate include:

First Name

Last Name

Employee Type

Title

Sex

Prefix

Employee Number

Hire Date

Date of Birth

y
l
n

3. Create your packages in SQL*Plus. They may look like the User Packages to Call
APIs scripts included below.
Note: Be sure to identify your
solution by using your unique team number in place of xx in the files or listed
solutions.

O
e

I
A

s
U

4. Run your package, passing specific parameter values for your employee. You can create
a procedure similar to the User Procedure to Call User Script below, or use the file
provided by your instructor.

&
l
a

5. Commit your work in SQL*Plus. Then navigate into the Application to verify that your
employee has been entered.

n
r
te

SQL Script Notes:

n
I
e

- Be certain to uniquely name your procedure, include your unique group number as
part of the name.

l
c
a

-You may need to adjust the person_type_id to the employee type in your setup.
Normally you will query for required Ids in your SQL script.

r
O

-You may also need to check the actual codes used for titles: recall that there is a
displayed title and a system title (the actual code instead of the meaning).

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 5

Calling an API: Practice Solution


Solution: User Packages to Call APIs
create or replace package tutor_upload_xx as
/* $Header:.... some header file details $ */
procedure person_details
(p_validate in boolean default false,
p_employee_number
in out varchar2,
p_last_name in varchar2,
p_first_name
in varchar2,
p_title
in varchar2,
p_hire_date in date,
p_date_of_birth in date,
p_sex in varchar2,
p_prefix
in varchar2);

end tutor_upload_xx;
/
create or replace package body tutor_upload_xx as
procedure person_details
(p_validate in boolean default false,
p_employee_number
in out varchar2,
p_last_name in varchar2,
p_first_name
in varchar2,
p_title
in varchar2,
p_hire_date in date,
p_date_of_birth in date,
p_sex in varchar2,
p_prefix
in varchar2)

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

is
-- Normally you would SELECT business group and person type
details.
-- For simplicity we hardcode local variables.
--- If you're going to use this script then you need to find
out the
-- business group Id that you are using and the person type Id
for

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 6

-- the 'Employee' person type on your system.


-l_business_group_id
l_person_type_id

number default 2892;


number default 1855;

--- Declare local variables to hold values returned by cursors.


-l_title
l_sex

varchar2(15);
varchar2(15);

--- Declare variables to hold returned ( OUT ) parameter


values.
-l_person_id
number;
l_assignment_id
number;
l_per_object_version_number
number;
l_asg_object_version_number
number;
l_per_effective_start_date
date;
l_per_effective_end_date
date;
l_full_name
varchar2(80);
l_per_comment_id
number;
l_assignment_sequence
number;
l_assignment_number
varchar2(60);
l_name_combination_warning
boolean;
l_assign_payroll_warning
boolean;

y
l
n

O
e

I
A

&
l
a

s
U

---- Define cursors to convert meanings to codes.


--

n
r
te

cursor convert_title is
select hrl.lookup_code
from hr_lookups hrl
where hrl.lookup_type = 'TITLE'
and hrl.meaning = p_title;

n
I
e

l
c
a

r
O

cursor convert_sex is
select hrl.lookup_code
Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 7

from hr_lookups hrl


where hrl.lookup_type = 'SEX'
and hrl.meaning = p_sex;
begin
--- Find the codes for the title and sex meanings passed in to
the API.
-open convert_title;
fetch convert_title into l_title;
close convert_title;
open convert_Sex;
fetch convert_sex into l_sex;
close convert_sex;
--- This solution calls the create_gb_employee API.
-- You can use the global API, or another legislative version.
--

y
l
n

O
e

s
U

hr_employee_api.create_gb_employee(
p_hire_date
=> p_hire_date ,
p_business_group_id
=> l_business_group_id,
p_last_name
=> p_last_name,
p_first_name
=> p_first_name,
p_title
=> l_title,
p_sex
=> l_sex,
p_pre_name_adjunct
=> p_prefix,
p_person_type_id
=> l_person_type_id,
p_employee_number
=> p_employee_number,
p_date_of_birth
=> p_date_of_birth,
p_person_id
=> l_person_id,
p_assignment_id
=> l_assignment_id,
p_per_object_version_number => l_per_object_version_number,
p_asg_object_version_number => l_asg_object_version_number,
p_per_effective_start_date
=> l_per_effective_start_date,
p_per_effective_end_date
=> l_per_effective_end_date,

I
A

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 8

p_full_name => l_full_name,


p_per_comment_id
=> l_per_comment_id,
p_assignment_sequence
=> l_assignment_sequence,
p_assignment_number
=> l_assignment_number,
p_name_combination_warning
=> l_name_combination_warning,
p_assign_payroll_warning
=> l_assign_payroll_warning );
end person_details;
end tutor_upload_xx;
/

Solution: User Procedure to call User Script


This procedure loads employee data by calling the procedure you define earlier. Note that
employee number must match the HRMS setup: if the system generates the number, then do not
pass a value in the parameter.
declare
-- define values for parameters to your script
-- normally you would have data loaded into staging tables
-- and create a cursor to populate multiple rows.
-- For simplicity, we hardcode values.
-l_validate boolean := false;
l_employee_number varchar2(15);
l_last_name varchar2(40) := 'Tenley';
l_first_name varchar2(20) := 'Robert';
l_title varchar2(15) := 'MR.';
l_hire_date date := to_date('01-JAN-2001','DD-MON-YYYY');
l_date_of_birth date := to_date('01-JUL-1970','DD-MON-YYYY');
l_sex varchar2(15) := 'M';
l_prefix varchar2(15) := '';

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

begin
tutor_upload_XX.person_details_XX (
p_validate => l_validate,
p_employee_number => l_employee_number,
p_last_name => l_last_name,
p_first_name => l_first_name,

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 9

p_title => l_title,


p_hire_date => l_hire_date,
p_date_of_birth => l_date_of_birth,
p_sex => l_sex,
p_prefix => l_prefix);
end;
/

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 10

Practice: Data Pump


The objective of this demonstration and practice is to use Data Pump by creating a batch to load
employee data. Run Data Pump from the Submit Reports and Processes window to load the data.
Given a scenario that you need to convert data from a legacy system, you want to
programmatically enter employee data into a configured Oracle HRMS system. You can use
Data Pump to call the HRMS APIs.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 11

Practice Solution: Data Pump


Create Batch Header and Lines
Create a Data Pump batch in SQL*Plus, using the solution below or the file provided by your
instructor. Be certain to replace xx with your unique team number. Note the hrdpp_ call,
specifying global or legislative functions.
The following SQL statements must be run within the APPS SQL*Plus schema.
declare
l_batch_id number;
l_per_object_version_number number;
l_asg_object_version_number number;
l_per_effective_start_date date;
l_per_effective_end_date date;
l_full_name varchar2(80);
l_per_comment_id number;
l_assignment_sequence number;
l_assignment_number varchar2(15);
l_name_combination_warning boolean;
l_assign_payroll_warning boolean;
l_employee_number varchar2(15) := null;

y
l
n

O
e

l_last_name varchar2(40) := 'HRTech';


l_first_name varchar2(20) := 'Employee';
l_person_user_key varchar2(40) := null ||' : hrtechxx per user
key';
l_assignment_user_key varchar2(40) := null ||' : hrtechxx asg
user key';
l_title varchar2(15) := 'Mr.';
l_hire_date date := to_date('2001/01/01','YYYY/MM/DD');
l_date_of_birth date := to_date('1970/07/01','YYYY/MM/DD');
l_sex varchar2(15) := 'Male';

I
A

&
l
a

s
U

n
r
te

begin
l_batch_id := hr_pump_utils.create_batch_header
('HRTECH_XX Batch Header', 'Vision
Corporation');
hrdpp_create_gb_employee.insert_batch_lines
(p_batch_id => l_batch_id,
p_user_sequence => null,
p_link_value => 1,
p_person_user_key => l_person_user_key,

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 12

p_assignment_user_key => l_assignment_user_key,


p_last_name => l_last_name,
p_first_name => l_first_name,
p_employee_number => l_employee_number,
p_title => l_title,
p_hire_date => l_hire_date,
p_date_of_birth => l_date_of_birth,
p_sex => l_sex,
p_user_person_type => 'Employee');
end;
/
Submit the Data Pump Concurrent Process
1. Navigate to the Submit Processes and reports window using your Super HRMS Manager
Responsibility:
(N) Processes and Reports > Submit Process and Report > Single Request
2. In the Request Name field, select Data Pump Engine in the list of values.
3. In the Parameters window select your batch name into the Batch field; Validate
corresponds to the API p_validate parameter: use the default No value to both validate
and complete the process.

y
l
n

O
e

4. Select the Submit Request button.


5.

View the results of the report.


Reports > View Requests > Find All My Requests

I
A

Verify the Data Load

s
U

(N) Processes and

Verify the data that you loaded by querying your employee in the application.

&
l
a

1. Navigate to the Person window using your Super HRMS Manager Responsibility:
(N) People > Enter and Maintain > (Find) < your employee >

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 13

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: APIs and Data Pump Demos and Practices


Chapter 10 - Page 14

HRMS Interfaces: Tools and


Utilities Demos and Practices
Chapter 11

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: Tools and Utilities Demos and Practices


Chapter 11 - Page 1

Practice: Batch Element Entry API


The objective of this demonstration and practice is to consider the options for element entry.
BEE (Batch Element Entry) tables can process new entries as well as updates and overrides for
assignment element entries.
The options for BEE include the professional user interface forms and a
Batch_element_entry_API, which you can call from SQL*Plus. In either case, once the
Pay_batch_headers and Pay_batch_lines tables are populated, you can run the BEE process from
the Submit Reports and Processes window to validate, transfer, or purge element entry data.
Given a scenario that you need to convert data from a legacy system, investigate the options to
determine how to use BEE tables in your solution.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: Tools and Utilities Demos and Practices


Chapter 11 - Page 2

Practice Solution: Batch Element Entry API


Create a BEE Batch: Professional Interface Forms
1. Login to the application and select your groups responsibility.
2. Set your effective date to 01-JAN-2001.
3. Use the element provided by your instructor, or define a new element for example,
Vacation Entitlement_XX, as an 'Information' type primary classification.
4. Identify or define input(s) for the element for example, Yearly Allowance.
5. Identify or define an element link for the new element and link it to all Payrolls.
6. Reset the session date to todays date.
7. Using the Person form, find the employee you entered. Navigate to the Assignment form
and ensure that s/he is assigned to a payroll
8.

Note the assignment number: _________

9. Using the Batch Element Entry form, create a new batch, for example, Tutor Vacation
Entitlement.
10. Create at least one batch line to load a value for your new element.

y
l
n

O
e

11. Query the BEE batch tables (Pay_Batch_Headers and Pay_Batch_Lines) for your batch.
Note: You can also enter data into these tables using the public API,
PAY_BATCH_ENTRY_API.

I
A

s
U

12. Submit the BEE process, selecting Transfer to move the data into the application.

13. When the process has completed running, check the status of the batch and associated
lines.

&
l
a

14. Check that your employee has the new element entry.

n
r
te

n
I
e

Reference: Pay_Batch_Element_Entry_API

l
c
a

The pay_batch_element_entry_api is available in the package pybthapi.pkh.


The procedures include:
create_batch_header,
create_batch_line,
create_batch_total,

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: Tools and Utilities Demos and Practices


Chapter 11 - Page 3

update_batch_header,
update_batch_line,
update_batch_total,
delete_batch_header,
delete_batch_line,
delete_batch_total

Reference: BEE Batch Tables


SQL> desc pay_batch_headers;
Name
--------------------------BATCH_ID
BUSINESS_GROUP_ID
BATCH_NAME
BATCH_STATUS
ACTION_IF_EXISTS
BATCH_REFERENCE
BATCH_SOURCE
COMMENTS
DATE_EFFECTIVE_CHANGES
PURGE_AFTER_TRANSFER
REJECT_IF_FUTURE_CHANGES
LAST_UPDATE_DATE
LAST_UPDATED_BY
LAST_UPDATE_LOGIN
CREATED_BY
CREATION_DATE
OBJECT_VERSION_NUMBER

Null?
-------NOT NULL
NOT NULL
NOT NULL
NOT NULL

n
r
te

l
c
a

n
I
e

r
O

y
l
n

O
e

I
A

&
l
a

SQL> desc pay_batch_lines;


Name
--------------------------BATCH_LINE_ID
COST_ALLOCATION_KEYFLEX_ID
ELEMENT_TYPE_ID
ASSIGNMENT_ID
BATCH_ID
BATCH_LINE_STATUS

Type
---NUMBER(15)
NUMBER(15)
VARCHAR2(30)
VARCHAR2(30)
varchar2(30)
varchar2(30)
varchar2(30)
varchar2(2000)
varchar2(30)
varchar2(30)
varchar2(30)
DATE
NUMBER(15)
NUMBER(15)
NUMBER(15)
DATE
NUMBER(9)

s
U

Null?
Type
-------- ---NOT NULL NUMBER(15)
NUMBER(9)
NUMBER(9)
NUMBER(10)
NOT NULL NUMBER(15)
NOT NULL VARCHAR2(30)

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: Tools and Utilities Demos and Practices


Chapter 11 - Page 4

ASSIGNMENT_NUMBER
BATCH_SEQUENCE
CONCATENATED_SEGMENTS
EFFECTIVE_DATE
ELEMENT_NAME
ENTRY_TYPE
REASON
SEGMENT1

SEGMENT30
VALUE_1
)
VALUE_15
ATTRIBUTE_CATEGORY
ATTRIBUTE1

ATTRIBUTE20
EFFECTIVE_START_DATE
EFFECTIVE_END_DATE
OBJECT_VERSION_NUMBER

varchar2(30)
NUMBER(9)
varchar2(240)
DATE
varchar2(80)
varchar2(1)
varchar2(80)
varchar2(60)
varchar2(60)
varchar2(80)
varchar2(80)
varchar2(30)
varchar2(150)
varchar2(150)
DATE
DATE
NUMBER(9)

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: Tools and Utilities Demos and Practices


Chapter 11 - Page 5

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: Tools and Utilities Demos and Practices


Chapter 11 - Page 6

HRMS Interfaces: ADE


Demos and Practices
Chapter 12

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 1

Practice: ADE Styles and Upload Modes


The objective of this demonstration and practice is to use ADE:
- in Application mode creating a Style and extracting data from a Folder, and
- in Standalone mode to upload data;
- in Application and Standalone to Fetch and Upload Salary Proposals.
Requirements
Given a scenario that an HR Administrator needs to use sensitive HRMS data on a desktop,
examine the options for creating Styles in ADE; the user wants to manipulate data on the
desktop, and upload it back to the Application, with complete validation.
Note that the Salary Proposals API is designed only for proposal entry, not for approving
proposals. The Salary:Approve function is often performed by a different role and separate from
proposal entry. The Super HRMS Manager Responsibilitys menu includes the function.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 2

Solution: ADE Styles


Part 1: Create an ADE Style
1. Logon to ADE as the sysadmin user:
button, choose Run, enter HRIO.exe

from the Start

2. When the ADE icon is available, logon as Sysadmin; both user and password are
Sysadmin.
3. Select the Styles tab
4. Select the Create Style button. Enter a Style Name = <Your style name> for example,
Tutor View XX
5. Form Name = GENERAL
6. Check the Multiple Rows box.
7. Enter or pick from list the reporting view name you created earlier.
8. Save your changes; Select the Style Columns tab.

y
l
n

9. Select the style name (for the style created above).

10. Select the Default button (to automatically create style columns from the view
definition). You can remove columns or change their display properties.

O
e

11. Save your work.

I
A

Test the Style

s
U

1. Logon to ADE as your application user, for example, HRMS01.

&
l
a

2. Select your Super HRMS Manager responsibility.

n
r
te

3. In the Query Details field, select the style you created

n
I
e

4. Execute your style query by clicking on the Fetch box

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 3

Solution: Using ADE Upload


Use ADE to Upload Data
The object of this practice is to upload data using ADE. You can use an API directly, or create a
user script to call an API. This practice uploads basic person data for employee person types:
First Name
Last Name
Title
Prefix
Employee Number
Hire Date
Date of Birth
This practice consists of:
Part 1 - creating the API procedure
Part 2 - creating an Upload Style
Part 3 - testing the Style with Upload

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 4

Part 1: Create the API Procedure


Use the API procedure you created earlier as a template for uploading data. You identify this as
the API to upload data from your desktop into HRMS.
This procedure loads basic Employee person data into the application.
Note: QuickCodes are used for entering titles for gender, title, and so forth. Be certain you are
using the correct code and not the displayed meaning of the QuickCode.
Your procedure may look like the following.
create or replace package ade_upload_xx as
/* $Header:.... some header file details $ */
procedure person_details
(p_validate
in
boolean default false,
p_employee_number
in out varchar2,
p_last_name
in
varchar2,
p_first_name
in
varchar2,
p_title
in
varchar2,
p_hire_date
in
date,
p_date_of_birth in
date,
p_sex
in
varchar2,
p_prefix
in
varchar2);
end ade_upload_xx;
/
create or replace package body ade_upload_xx as
procedure person_details
(p_validate
in
boolean default false,
p_employee_number in out varchar2,
p_last_name
in
varchar2,
p_first_name
in
varchar2,
p_title
in
varchar2,
p_hire_date
in
date,
p_date_of_birth in
date,
p_sex
in
varchar2,
P_prefix
in
varchar2)

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O
Is
--

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 5

O
e

y
l
n

-- For simplicity, business group and person type


are hardcoded into local variables.
--- Identify the actual values that you need here
-- Vision US: BG 202; EMP = 13
-- Vision UK: BG 626; EMP = 95
l_business_group_id
l_person_type_id

-- Ids

number default 626;


number default 95;

--- Declare local variables to hold values


-- returned by cursors.
-l_title
l_sex

varchar2(15);
varchar2(15);

--- Declare variables to hold


-- returned ( OUT ) parameter values.
-l_person_id
number;
l_assignment_id
number;
l_per_object_version_number
number;
l_asg_object_version_number
number;
l_per_effective_start_date
date;
l_per_effective_end_date
date;
l_full_name
varchar2(80);
l_per_comment_id
number;
l_assignment_sequence
number;
l_assignment_number
varchar2(60);
l_name_combination_warning
boolean;
l_assign_payroll_warning
boolean;
--- Define cursors to convert meanings to codes.
-cursor convert_title is
select hrl.lookup_code
from hr_lookups hrl
where hrl.lookup_type = 'TITLE'

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 6

O
e

y
l
n

and

hrl.meaning = p_title;

cursor convert_sex is
select hrl.lookup_code
from hr_lookups hrl
where hrl.lookup_type = 'SEX'
and hrl.meaning = p_sex;
begin
--- Find the codes for the title
-- and sex meanings passed to the API.
-open convert_title;
fetch convert_title into l_title;
close convert_title;
open convert_Sex;
fetch convert_sex into l_sex;
close convert_sex;
--- Call the create_gb_employee API.
--- If you're using a US business group then call the
-- create_us_employee API.
-hr_employee_api.create_gb_employee(
P_hire_date
=> p_hire_date ,
P_business_group_id
=> l_business_group_id,
P_last_name
=> p_last_name,
P_first_name
=> p_first_name,
P_title
=> l_title,
P_sex
=> l_sex,
P_pre_name_adjunct
=> p_prefix,
P_person_type_id
=> l_person_type_id,
P_employee_number
=> p_employee_number,
P_date_of_birth
=> p_date_of_birth,
P_person_id
=> l_person_id,
P_assignment_id
=> l_assignment_id,
P_per_object_version_number => l_per_object_version_number,
P_asg_object_version_number => l_asg_object_version_number,

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 7

P_per_effective_start_date
=> l_per_effective_start_date,
P_per_effective_end_date
=> l_per_effective_end_date,
P_full_name
=> l_full_name,
P_per_comment_id
=> l_per_comment_id,
P_assignment_sequence => l_assignment_sequence,
P_assignment_number
=> l_assignment_number,
P_name_combination_warning
=> l
l_name_combination_warning,
P_assign_payroll_warning
=> l_assign_payroll_warning );
end person_details;
end ade_upload_xx;
/
/*

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 8

Part 2: Create a New ADE Style to Upload Data


Create a New ADE Style to Upload Data
1. Logon to ADE as the 'sysadmin' user.
2. Select the 'Styles' tab.
3. Select the 'Create Style' button.
4. Style Name = <Your style name> for example, Tutor Person View Upload Form Name
= GENERAL.
5. Check the 'Multiple Rows' box.
6. Enter or pick from list the reporting view name you created earlier
7. Upload API: Enter the name of the upload API created earlier.
8. Save your changes.
9. Select the 'Style Columns' tab.
10. Select the style name (for the style created above).

y
l
n

11. Select the 'Default' button (to automatically create style columns from the view
definition).

O
e

s
U

12. Remove style column fields not requied; organization, person type, and job, using the
'Cut' button.

I
A

13. Change the 'Upd' attribute to '1' (updateable API column) for all columns.

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 9

Part 3 - Testing a New Style


1. Logon to ADE as your application user, for example, group1.
2. Select your groups responsibility.
3. In the 'Query Details' field, select the new style you just created (above).
4. Execute your style query by clicking on the 'Fetch' box.
5. Click on the 'Sheet' button to export the data to your spreadsheet.
6. Select all rows of data from the spreadsheet apart from the first row.
7. Change the values of the fields for the remaining row (enter details for a new person).
8. With Excel (or your spreadsheet application) save the contents of the spreadsheet to a
file name of your choice, for example, group1_person_details.
9. Exit ADE.
10. Login to ADE, using the standalone upload desktop icon (or from Start > Run) as your
application user.

y
l
n

11. Select your groups responsibility.

O
e

12. Click on the 'Load' button and select the spreadsheet you created earlier.

s
U

13. Mark the displayed row for attempted upload by double-clicking the cursor on the row
twice (in quick succession).

I
A

14. Click the 'Upload' button to upload the data into the application.

If you are having problems calling your upload API, set ADE trace on by assigning the
value 'ON' to the environment variable HRIO_TRACE. You can do this within the
control panel of your computer (if running Windows NT). This will produce a
HRIO.API trace file showing exactly how ADE is calling the upload API procedure.

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 10

Part 5: Salary Upload


This separate practice demonstrates delivered Salary Upload functionality .
1. Using your Super HRMS Manager responsibility, enter the Salary Management window:
(N) > People > Salary Management
2. Execute a query using %xx% in the fullname field, to select records for employees
whose suffix includes your unique team number.
3. Invoke ADE by pressing the ADE spreadsheet icon.
4. Select Spreadsheet and the Salary Proposals style.
5. Select Start, launching Excel and exporting the data to your spreadsheet.
6. The Payroll Administrator might analyze and identify salary change proposals on the
desktop: enter salary proposals and Change Date for some employees.
Employee ____________ Salary proposal______________ Date_____
Employee ____________ Salary proposal______________ Date_____
Employee ____________ Salary proposal______________ Date_____

y
l
n

7. Save the changes to the default HRIO.EXE or, if you choose another name, note it here:
_____________.

O
e

8. In the Application, again invoke ADE.

I
A

9. Select the Upload button

s
U

10. At the preview screen select Load and choose the spreadsheet file that you saved. You
can then preview the data in the preview window.

&
l
a

11. Select Upload to load the data into the HRMS tables.

n
r
te

12. On completion you can check the upload by returning to the Salary Management folder
and re-querying the appropriate records.

n
I
e

13. Navigate to the Salary Management window:


(N) People > Salary Management.

l
c
a

14. Query the employees you previously extracted.

r
O

15. Approve the salary changes: select the employee record; then press Approve.
16. Save your changes.
Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 11

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

HRMS Interfaces: ADE Demos and Practices


Chapter 12 - Page 12

Extending Business
Rules in HRMS
Chapter 13

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 1

11i Oracle HRMS: Extending Business Rules in HRMS

11i Oracle HRMS: Extending Business


Rules in HRMS

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 2

Objectives
Objectives
After completing this module, you should be able to
describe HRMS Extension Features, including:
Logic extensions
Forms Configurator and Templates
Custom Security extensions

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This module describes the HRMS product components that enable customers
and users to extend business rules by:
Using Custom Library to define specific and nearly limitless logic
extensions
Attaching code to API User Hooks
Understanding the recommended approach to and limits of HRMS
extensions
Creating FastFormula components and calls
Forms Configurator definition of user-interfaces
Configuring security profiles on employee data
We presume the audience is familiar with the HRMS API business process
approach, FastFormula, PL/SQL, and System Administration tasks. A
comprehensive understanding of HRMS functionality empowers you with the
full benefit for defining extension features.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 3

Agenda
Agenda
Extending Business Rules Module includes
Extension Restrictions
Custom Library
API User Hooks
FastFormula Extensions
Forms Configurator and Templates
Expanding Security

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 4

Agenda
Agenda
Extending Business Rules Unit includes
Extension Restrictions
Custom Library
API User Hooks
FastFormula
Functions, Database Items, Calls from PL/SQL

Forms Configurator and Templates

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
Extending Security is a addressed in a separate unit.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 5

Extensions and Restrictions

Extensions and Restrictions

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 6

Objectives
Objectives
At the end of this topic you should be able to
explain the recommended extensions and
restrictions, including the use of:
database triggers
database constraints

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 7

Agenda
Agenda
Business Rule Framework
Extension Guidelines

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This brief topic covers an important concept: recommended restrictions on
custom extensions. The entire module introduces and advocates extensions that
retain HRMS data and process integrity.
What is and is not covered
This topic focuses on HRMS-specific custom extensions that are not detailed in
other topics of these modules.
This topic is not a substitute for AOL (Applications Object Library) and ATG
(Applications Technology Group) products and courseware. ATG and AOL
offer fundamental and detailed features beyond the scope of this course.
Extensions such as Custom Forms, which are delivered Forms with security
restrictions defined with System Administration functionality, also are not in the
scope of this topic.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 8

Business Rule Framework


Business Rule Framework
Database
Form

Data Model

Batch
Processes

Core HRMS APIs

Hooked Code
CUSTOM
Library

User Defined API calls &


PL/SQL Formula APIs

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

The Business Rule Framework


This recommended business rule framework demonstrates how extensions fit
into the delivered HRMS product.
Examples of extensions include:
Custom Library code access Form functionality
User calls to published APIs SSHR and new functionality use APIs
Hooked Code, such as custom PL/SQL attached to User Hooks in API
processes
User Formulas
Multiple User Hooks are predefined at many business process points; normally
you can attach a rule before or after the process. Application forms access
Custom Library, where you can attach many types of rules, including calls to
Formula.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 9

API Layers and Triggers


API Layers and Triggers
Custom / Alternative Interface layer

Business Process layer


Published APIs
Oracle Applications
Internal Code Layers

Business Support layer

Row Handler layer

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Core Functions and Insulating Code Layers


Detailed discussion of HRMS architecture and APIs includes row handlers and
business support layers, which may be grouped into business processes.
Business processes act as a single transaction that succeeds or fails, impacting
multiple components in lower layers. Legislative code is hooked into these
layers. APIs provide an insulating layer to distinct processes, ensuring data and
processing integrity.
Why to Avoid Custom Triggers and Constraints
Triggers and constraints are integral to the HRMS low-level design. This makes
them difficult to use successfully at the customer level. The customer level is
designed to be the easiest and safest place for customers to create extensions;
extensions in other areas can compromise upgrades.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 10

Factors that contribute to user-triggers and constraints issues include:


Triggers are low-level compared to the business process layer.
Table changes are hidden from the business process layer. Mutating tables
create limitations, for example: you cannot select values from any row in a
table that is being modified. This restriction prevents complex validation
in database triggers.
Datetracked features make implementing triggers more complex:
DateTrack carries out extra row manipulation logic which can affect more
than one row in a table for one user change.
Debugging can be extremely difficult and time-consuming when custom
triggers are applied to protected layers.
Legislation and other business rules can easily be compromised if custom
triggers interfere with processing.
Upgrades are made complex, and custom triggers or constraints may
conflict with new delivered triggers.
Triggers fire for all specified DML operations. You cannot determine the
process that caused the event. You cannot access legislation context on
core tables.
Trigger Usage
HR Development uses triggers and constraints on legislation-specific tables.

Development avoids using triggers on core tables.

Triggers are used in Oracle primarily for audit, including the WHO
columns.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 11

Survey of Delivered Extensions


Survey of Delivered Extensions
Flexfields: Descriptive, Key, Extra Information,
Special Information Types
HRMS Custom Forms and Taskflows
Forms Configurator
Folders and Folder Tools

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Survey of Delivered Extensions


This module continues its discussion of extension options. Several of the
features in this topic are covered in more detail in other topics; some topics are
covered in other (implementation and end-user) courses. The topics are included
to provide a survey of the extension options available in HRMS. Substantial
reference material on these topics is available in online help and on Metalink.
Flexfields
Flexfields are a delivered feature that provides supported and upgradeable
extension to business rules. Specific flexfield information for setup and function
are not in the scope of this topic; however, each type of flexfield has some
unique features that you can consider for specific business requirement
extensions. This overview indicates some of those features.
Descriptive Flexfields allow you to store data on specific entities, such as
person, assignment, or element. Only one structure is permitted in a business
group, but global and context-sensitive segments can be defined. Restrictions
that you need to consider include accessing Forms values from extensions, such
as in Custom Library.
Key Flexfields are integrated into the product: you configure most key
flexfields; others are protected. Key flexfield combinations are stored in
separate tables: for example, an assignment record includes the foreign key to a
job, position and grade (if used); but the Special Information Type flexfield
allows multiple occurrences or child records per entity.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 12

Flexfield naming conventions may vary, but two concurrent processes enable
you to easily access flexfield information:
A process to generate database items from specified flexfields permits
their access in elements, QuickPaint reports, and other Formula features
A process to generate business views allows you to access flexfield data
from an end-user perspective.
Protected flexfields should not be modified and are subject to change.
Localization teams define protected or Developer Descriptive Flexfields.
Extra Information Types
Unprotected, or customer-configurable, Developer Descriptive Flexfields are
available on entities as EITs (Extra Information Types) and controlled by
legislation definition. You can configure these flexfields, which are held on
separate tables (in contrast to other Descriptive Flexfields). You have the option
of allowing multiple occurrences of EITs.
Most EITs can be included in taskflows; the Organization EIT is an exception.
Entities that have EITs available include:
Jobs
Positions
Locations
People
Assignments
Organizations
Special Information Types
SITs (Special Information Types) are key flexfields which have an ID stored as
a foreign key. An SIT Folder can is provided for listing people by SIT. An
additional consideration for SITs is that they are available from SSHR. Custom
Forms and Taskflows can use SIT to restrict access.
HRMS Custom Forms and Taskflows
Custom Forms is a delivered HRMS feature that allows you to provide multiple
versions of delivered forms, fitted to specific roles or users. System
Administrators create Custom Forms by restricting a delivered form using any
of the following:
Element Types or Element Sets
Person Functions or Person Types, such as Employee or Applicant
QuickPaint Reports
Special Information Types
Organization Classifications

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 13

Taskflows
Defining taskflows is another System Administrative option for extending
business rules. Taskflow refers to both navigator access to forms and to the
internal form flow using buttons. You create a taskflow using delivered or
Custom Forms for which you specify buttons to other forms. You can rename,
change, or remove buttons that access other forms. Components that can be
identified on a custom taskflow include:
Delivered and custom forms
User-defined folders
User-designed localized forms
For example, if you wanted to create a copy of the Person form for a
receptionist, you might remove buttons which access address or assignment.
Most components of the menu, data, tasks and many levels of security can be
implemented using standard administration features.
Forms Configurator
Forms Configurator allows access to many Forms Developer field attributes,
enabling you to use delivered forms as an interface to design user-forms based
on delivered templates. You can define most individual field characteristics and
many extension features normally accessed only through System Administration
or Developer. Items such as: taskflow, include Descriptive Flexfields, SIT, and
EIT, are all available. DateTrack and Workflow messaging can be enabled.
Folders
Folders are based upon predefined views that store your queries. Folders are
delivered for a user or administrator to configure by removing and formatting
columns. An export facility provides additional functionality from folders.
You can limit folder tool access through System Administration. For example,
an administrator may provide a view with public access, but restrict the tools so
that hidden columns cannot be added.
Note
The HRMS System Administration course includes comprehensive explanation
of these features. Note that the Applications System Administration may not
include HRMS-specific features.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 14

Configuration Options
Configuration Options
Flexfields and Validation
Help
Profile Options

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Configuration Options
Flexfields and Validation
Several validation options are available on flexfields, addressing complex rules
without coding and without impacting upgrades.
Extending or Configuring Help
You can configure Online Help without disturbing hypertext links and defined
navigation. You can add or replace help pages.
Profile Options
This course introduces a limited number of profile options. However, many
more profile options are available. You need to analyze the users, roles, and
responsibilities in your enterprise to determine how various profile options
should be set, and which may be available for user configuration.
For more information on AOL Profile Options, please refer to the Online Help
path:
Applied Technology > Oracle Applications System Administration > Profile
Options in Oracle Application Object Library
For more information on HRMS Profile Options, refer to the Online Help path:
Oracle HRMS > Security > User Profiles

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 15

Summary
Summary
Having completed this topic you should be able to:
Explain the problems encountered when using
database triggers and constraints
Discuss the possible uses of triggers and
constraints

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 16

Custom Library

Custom Library

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 17

Objectives
Objectives
At the end of this topic you should be able to:
Describe the Custom Library
Identify possible uses of Custom Library
Describe design considerations

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 18

Agenda
Agenda
Custom Library
Architecture and Components
Business Rules and Usage
Designing Solutions with Custom Library

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
The topic of this section is Custom Library as delivered and available to HRMS
(and other Oracle ERP Applications).
This topic does not focus on Developer Forms, Library restrictions, or PL/SQL;
but it refers to features of those tools for extending HRMS.
Reference
For detailed reference, please see White Papers on Metalink at:
> Technical Libraries > ERP Applications > HRMS > White Papers >
Technical Issues
Using Custom Library within Oracle HRMS Applications, Doc ID: 73505.1
and
Note Doc ID: 45759.1, Custom Development in Applications, a FAQ
(Frequently Asked Questions) for various extension integration points.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 19

What Is Custom Library?


What Is Custom Library?
Forms Library
PL/SQL Code Accessed at Runtime

Extend Logic Without Modifying Delivered Code


Integrates Your Custom Code Directly with
Delivered Applications
Supported, Upgradeable, Partitioned Repository for
Custom Code
Easily Disabled for Debugging and Support

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Custom Library
This library is an Oracle Developer Forms Library delivered with the ERP
Applications. It includes sample code for extending business rules with
Application Form events and calls.
Certain Form events trigger calls to the library. For example, when a user
navigates or clicks a specific icon, the Forms trigger calls Custom Library. The
library code can execute logic that you inserted. You can define conditional
logic, for example, having the library execute different code for a specific form,
user, or field value.
The Custom Library functionality is available to all ERP modules; however, the
HRMS application has extended the functionality of Custom Library.
Custom.pll is available on the Application server middle tier. You can access
the library from Forms Developer, extending business rules with code for
specific events. Because the library is external to the Forms, code changes are
defined and retained separately from Forms.
Note: At upgrade, validate that your custom code functions as designed, since
other delivered changes may impact behavior.
Custom Library can be switched on or off, using the Toolbar Help >
Diagnostics, which is controlled with the profile option Utilities:Diagnostics
and password.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 20

Custom Library Architecture


Custom Library Architecture

Application Functions and Calls

VERT
Library

APPCORE
Library
GLOBE
Library

JA

JE

Application Form
CUSTOM
Library

JL

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Architecture
New Application forms are based on a TEMPLATE form. You can use this
same form that HR Development uses; if you follow AOL Standards (see
Extending Oracle Applications with Developer, ATG Courseware) your custom
forms look and behave similarly to Oracle Application forms.
The template form has standard event triggers that call the Appcore library (first
arrow, above). Appcore contains standard routines and procedures that provide
the Oracle applications look and feel. Appcore contains packages and
procedures for menu, toolbar, and other standard form components.
Appcore calls other libraries, as noted in this simplified diagram, but only
Custom library is designed for customer use. Other libraries are used
exclusively by Oracle Applications Product Development teams, such as:
VERT verticalization code
GLOBE globalization code
JA Asia Pacific development features
JE EMEA development features
JL Latin America development features
CUSTOM is reserved for customer specific logic.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 21

Custom Library Structure


Custom Library Structure
PACKAGE custom IS
function
function
procedure
before
after
override
standard

zoom_available
style(event_name
event(event_name
constant integer
constant integer
constant integer
constant integer

varchar2)
varchar2);
:= 1;
:= 2;
:= 3;
:= 4;

return BOOLEAN;
return integer;

END custom;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Custom Library Structure


Custom Library, reserved for your custom code, contains the custom package
definition, which must remain intact. The library also contains example code
and instructive comments.
Using custom library, you can design your solutions to address business needs,
down to field-level values. For example, if a user clicks an icon, the Forms
event is passed to the libraries.
Code at any event is executed unconditionally. However, you can include
conditional logic within your code. For example, you can check for the specific
event, then define conditional code using if statements to identify actions
depending on the calling form, user, or a form field value.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 22

Uses of the Custom Library


Uses of the Custom Library
Sample Business Requirements:
Switch to Another Form
Extend Validation at Event Points
Generic event points
Product specific events
custom.before / after / override / standard

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Uses of the Custom Library


Three categories identify Custom Library usage:
Define Zooms: enables you to jump from one form to another. The new form
can be any other form within the ERP modules. Context information can be
passed between the two forms as parameters.
Additional user logic at generic event points: these event points are available
from within all ERP module forms.
Custom logic at product specific event points: each application team defines
additional event points for their specific modules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 23

Zooms: Jump to Form


Zooms: Jump to Form
Retain Context Information
Freezes Current Open Form
Enables Icon: Jump to Another Form
Zoom Event Triggered by User
FND_FUNCTION (not Form calls) Controls Activity

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Zoom Functionality Overview


Enable button using ZOOM_AVAILABLE
Define the record group for the zoom LOV, if multiple destination Forms
are user option
Identify destination Form in event procedure
FND_FUNCTION calls new form
Zoom enables you to jump from one form to another form and pass any required
contexts or parameters. For example, you can define a zoom to jump from the
enter and maintain person form to a form in the G/L application or to a form in
Oracle Projects.
Setup Steps:
First identify the Form on which to enable the zoom feature. When you identify
the source form in Custom Library, the zoom icon in the Application toolbar
will be enabled in that form. Beginning in R11i, you can identify multiple
destination forms for a single form zoom: you define a record group to identify
the multiple forms.
Finally, use FND_FUNCTION to specify the destination form function within
the specific zoom EVENT procedure.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 24

Zoom: Enable Zoom


Zoom: Enable Zoom
package body custom is
function zoom_available return boolean is
form_name varchar2(30) := name_in('system.current_form');
block_name varchar2(30) := name_in('system.cursor_block');
begin
if (form_name = 'DEMXXEOR
return TRUE;
else
return FALSE;
end if;

and block_name= 'ORDERS') then

end zoom_available;
end custom;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Zoom Code: Specify Form and Block


When a user presses the enabled zoom icon, your associated zoom code
referring to the source form and block is executed.
The above code demonstrates enabling a zoom in a specific form and block: the
DEMXXEOR form and the ORDERS block; the boolean value indicates zoom
availability. When the value is TRUE, the zoom icon is enabled.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 25

Zoom: Call New Form


Zoom: Call New Form
package body custom is
procedure event(event_name varchar2) is
if (event_name = 'ZOOM') then
if (form_name = 'DEMXXEOR' and block_name =
'ORDERS') then
fnd_function.execute(FUNCTION_NAME=>'DEM_DEMXXEOR',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y',
OTHER_PARAMS=>'ORDER_ID="'||param_to_pass1||

end if;
end if;
end event;
end custom;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Zoom Code: Execute Destination Form


The procedure FND_FUNCTION.EXECUTE calls the new form. The current
form is suspended and the new form is called. Any parameters are passed in the
function call.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 26

Generic Event Points


Generic Event Points
Specific Forms Triggers

Many Navigation Triggers


Implicit-Navigation: Record Validate
Zoom
Export

Additional Events with Each Release


R11i: At Responsibility, Logon, or Password Change

Copyright Oracle Corporation, 2001. All rights reserved.

Generic Event Points


These event names refer to Forms triggers; the Release identifies when the
events became available.
R10
When-new-form-instance
When-new-block-instance
When-new-record-instance
When-new-item-instance
When-validate-record
zoom
export
R11
When-form-navigate
specialn
R11i
Key-fn

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 27

Event Code Structure


Event Code Structure
package body custom is
procedure event(event_name varchar2) is
form_name varchar2(30):= name_in('system.current_form');
block_name varchar2(30):= name_in('system.cursor_block');
begin
if (event_name = 'WHEN-VALIDATE-RECORD') then
if (form_name = 'PERWSHRG' and block_name =
'PERSON') then

end if;
end if;
end event;
end custom;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Event Code Structure


Identify the EVENT procedure in the Custom Library for your custom code.
Since Custom Library is shared among ERP Applications, you specify as much
information as required to restrict the action. Otherwise, your code
inadvertently impacts other Application users. You can limit the action by many
factors, including:

Application ID

User ID or Responsibility ID

Calling Form and Block.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 28

Product Specific Events


Product Specific Events
Additional Navigation and Validation Triggers
When-button-pressed

DateTrack Events
DT_CALL_HISTORY
DT_SELECT_MODE

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HRMS Product-Specific Events


HRMS Development delivers additional product-specific Custom Library event
points. These events reflect customer requests and real-world business
requirements.
New HRMS events in R11i are:
WHEN-BUTTON-PRESSED: Enables you to perform
custom validation before a button is pressed.
DT_CALL_HISTORY: Enables you to change which
database view is used by datetrack history.
DT_SELECT_MODE: Enables you to restrict the datetrack
modes a user can select.
Product-Specific Event, Release Availability, and Product Area
R11- HRMS:
When-create-record
Pre-insert
Post-insert
Key-delrec
Post-forms-commit
pre-delete
post-delete

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 29

post-query
pre-update
post-update
navigate
R11i - HRMS
dt-call-history
dt-select-mode
when-button-pressed
R11i - AOL
when-responsibility-changed
when-password-changed
when-logon-changed

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 30

Custom Library Uses


Custom Library Uses
Change Form Properties
Change Window Title
Select Date Track History View
Reduce Date Track Options

Change Form field properties


Default and Conditional Field Logic

Add Validation
Execute Formula PL/SQL code
Call new forms

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Custom Library Uses


Custom Library is a delivered Forms PL/SQL library that allows you to access
and change Form attributes at runtime. Trigger points set events, so that you
need to only define your logic in the library, to extend business rules beyond the
delivered application. Examples of what you can do with Custom library
include:

Changing Form field properties, such as from optional to required

Highlighting a field by changing the color attribute

Adding additional validation to a field

Executing additional validation stored in a server side PL/SQL routine

Overriding a List Of Values

Overriding a Default Where Clause

Defaulting the value into a field


Note: Custom Library cannot create new form fields; it can hide boilerplate
text only if the boilerplate has accessible attributes.
You must observe all Supported constraints when using Custom Library, so as
not to interfere with HRMS data integrity.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 31

Example 1: Highlight Fields


Example 1: Highlight Fields
fnd_message.set_string('Would you like to highlight all '||
'required EMPLOYEE fields ? );
l_button_selected:=fnd_message.question(
button1
=> 'Cancel',
button
=> 'No',
button3
=> 'Yes',
default_btn => 2,
cancel_btn => 1,
icon=> 'question');
fnd_message.show;
if l_button_selected = 3 then
set_item_property('person.last_name',VISUAL_ATTRIBUTE,
'SELECTED_DATA');
set_item_property('person.sex',VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.date_of_birth',VISUAL_ATTRIBUTE,
'SELECTED_DATA');
end if;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 1: Highlight Fields


This example demonstrates a pop-up window for the user to choose a button
representing a display option (Yes, No, or Cancel).

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 32

Example 1: Highlight Fields


Example 1: Highlight Fields
fnd_message.set_string('Would you like to highlight all '||
'required EMPLOYEE fields ? ');
l_button_selected:=fnd_message.question(
button1
=> 'Cancel',
button2
=> 'No',
button3
=> 'Yes',
default_btn
=> 2,
cancel_btn
=> 1,
icon
=> 'question');
fnd_message.show;

if l_button_selected = 3 then
set_item_property('person.last_name',
VISUAL_ATTRIBUTE, 'SELECTED_DATA');
set_item_property('person.sex',
VISUAL_ATTRIBUTE, 'SELECTED_DATA');
set_item_property('person.date_of_birth',
VISUAL_ATTRIBUTE, 'SELECTED_DATA');
end if;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 1: Highlight Fields continued


If the user selects Yes, the code then sets form field visual_attribute to highlight
three fields in the person form. Values for visual_attribute selected_data are
identified or linked into the actual form.
Note: Custom code is entirely within the Custom Library EVENT.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 33

Example 2: Remove Field(s)


Example 2: Remove Field(s)
fnd_message.set_string('Would you like to remove the Mail To '||
'field ? ');
l_button_selected:=fnd_message.question(
button1
=> 'Cancel',
button2
=> 'No',
button3
=> 'Yes',
default_btn
=> 2,
cancel_btn
=> 1,
icon
=> 'question');
fnd_message.show;
if l_button_selected = 3 then
set_item_property('person.d_home',DISPLAYED,PROPERTY_FALSE);
elsif l_button_selected = 2 then
null;
else
null;
end if;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 2: Hide Field


This example demonstrates a pop-up user window for the user to choose display
options that include setting form field attributes to effectively hide the Mail
To field.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 34

Example 2: Remove Field(s)


Example 2: Remove Field(s)
fnd_message.set_string('Would you like to remove the Mail To '||
'field ? ');
l_button_selected:=fnd_message.question(
button1
=> 'Cancel',
button2
=> 'No',
button3
=> 'Yes',
default_btn
=> 2,
cancel_btn
=> 1,
icon
=> 'question');
fnd_message.show;

if l_button_selected = 3 then
set_item_property('person.d_home',DISPLAYED,
PROPERTY_FALSE_DATA');
elsif l_button_selected = 2 then
null;
else
null;
end if;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 2: Hide Field - continued


If the user selects Yes, the code then sets form field visual_attribute to hide the
field. Values for visual_attribute selected_data are identified or linked into the
actual form.
Note: boilerplate, such as the field label, can be referenced only if it has been
created with accessible attributes, including if it is created with Form
Configurator.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 35

Example 3: Override LOV


Example 3: Override LOV
if (event_name = 'WHEN-NEW-FORM-INSTANCE') then
if ( form_name = 'PERWSEPI') then
l_check:=populate_group_with_query('MARITAL_LOV',
'select hl.meaning||'||''' -- ADDED TEXT '''
|| ',hl.lookup_code from hr_lookups hl '
|| ' where hl.lookup_type='||'''MAR_STATUS'''
|| ' and
hl.enabled_flag = '
|| '''Y'''||' and :ctl_globals.session_date between '
|| 'nvl(hl.start_date_active,:ctl_globals.session_date) and '
|| 'nvl(hl.end_date_active,:ctl_globals.session_date) order
by hl.meaning');
end if;
else
null;
end if;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 3: Override LOV


This example shows how to override a form List Of Values.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 36

Example 3: Override LOV


Example 3: Override LOV
if (event_name = 'WHEN-NEW-FORM-INSTANCE') then

if ( form_name = 'PERWSEPI') then


l_check:=populate_group_with_query('MARITAL_LOV',
'select hl.meaning||'||''' -- ADDED TEXT
'''
|| ',hl.lookup_code from hr_lookups hl '

|| 'nvl(hl.end_date_active,'
|| ':ctl_globals.session_date) order by '
|| 'hl.meaning');
else
null;
end if;

Copyright Oracle Corporation, 2001. All rights reserved.

Example 3: Override LOV (List of Values)


The POPULATE_GROUP_WITH_QUERY function reassigns the Select
statement for the delivered Form LOV.
Note the library syntax of single quotes.

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 37

Example 4: Override Default Where Clause


Example 4: Override Default Where Clause
if (event_name = 'WHEN-NEW-BLOCK-INSTANCE'
or event_name ='WHEN-NEW-RECORD-INSTANCE' ) then
if (form_name = 'PERWSEPI' and block_name = 'PERSON') then
set_block_property('person',DEFAULT_WHERE,
'where (:CTL_GLOBALS.CUSTOMIZED_RESTRICTION_ID IS NOT NULL '||
'and ((exists (select 1 from pay_restriction_values prv1, '||
'per_startup_person_types pst, per_person_types ppt ');
end if;
end if;

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 4: Override Default Where Clause


The fourth example shows how to override a form default where clause.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 38

Example 4: Override Default Where Clause


Example 4: Override Default Where Clause
if (event_name = 'WHEN-NEW-BLOCK-INSTANCE'
or event_name ='WHEN-NEW-RECORD-INSTANCE' ) then
if (form_name = 'PERWSEPI' and block_name = 'PERSON') then

set_block_property('person',DEFAULT_WHERE,
'where (:CTL_GLOBALS.CUSTOMIZED_RESTRICTION_ID IS '
||' NOT NULL and
((exists (select 1 from '
||' pay_restriction_values prv1, '
||' per_startup_person_types pst, '
||' per_person_types ppt ');

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 4: Override Default Where Clause


The SET_BLOCK_PROPERTY command is used to reassign the default where
clause.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 39

Example 5: Call Server Side Procedure


Example 5: Call Server Side Procedure
fnd_message.set_string('Comparing amount against market survey
data);
fnd_message.show;
vision_cl_code.market_salary(
p_assignment_id =>to_number(name_in(
'global.g_assignment_id')),
p_approval_date => to_date(name_in('review.change_date'),
'YYYY/MM/DD'),
p_min_mkt_salary => l_min_mkt_salary,
p_max_mkt_salary => l_max_mkt_salary );

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 5: Call Procedure, Passing Parameters


The fifth example shows how to call a custom server side procedure. Before
executing the procedure, this code displays a message that informs the user
about the specific task.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 40

Example 5: Call Server Side Procedure


Example 5: Call Server Side Procedure
fnd_message.set_string('Comparing amount against market survey
data);
fnd_message.show;

vision_cl_code.market_salary(
p_assignment_id =>
to_number(name_in('global.g_assignment_id')),
p_approval_date =>
to_date(name_in('review.change_date'),
'YYYY/MM/DD'),
p_min_mkt_salary => l_min_mkt_salary,
p_max_mkt_salary => l_max_mkt_salary );

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 5: Call Procedure, Passing Parameters


The procedure has been created in the APPS schema in the database. This
specific procedure has four parameters, two input and two output.
Technical Note:
Please see the AOL Metalink Doc ID: 45759.1, Custom Development in
Applications, a FAQ (Frequently Asked Questions) for additional information
on various extension integration points.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 41

Example 6: Defaulting Field Values


Example 6: Defaulting Field Values
vision_cl_code.call_earn_poten_formula(
p_amount
=> to_number(name_in('entry.user_entry1')),
p_session_date
=>
to_date(name_in('ctl_globals.session_date'),
'DD-MON-YYYY'),
p_assignment_id => to_number(name_in('entry.assignment_id')),
p_earn_poten
=> l_earn_poten,
p_earn_mesg
=> l_earn_mesg );

copy(
replace(to_char(round(nvl(to_number(l_earn_poten),
1),2),'999999990.99'),'',''),'entry.user_entry2');
copy(name_in('entry.user_entry2'),
'entry.screen_entry_value2');

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Example 6: Default Field Values


The sixth example shows how to default some values in to form fields. In this
case were copying values to an element input after we have executed a custom
server side procedure.
Technical Note:
Library syntax requires indirect reference for accessing Form field values.
Detailed information is available in Developer or PL/SQL references and is
beyond the scope of this course.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 42

Design Considerations
Design Considerations
All ERP Applications Share Custom Library
Form Library Size Restriction
Option: Logically Nest Additional Libraries

CUSTOM

HRCUSTOM

HRCUST1

HRCUST2

PERWSHRG / PERWSEPI / PERWSEMA

PERWSEPY / PAYWSMEE / PERWSEAD

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Design Considerations
Custom Library is shared among all of the Oracle ERP applications. This means
that your code for an event may impact other users. For a simple example,
Purchasing may enter people as vendors and HR can view the same people.
Your code can add a validation restriction that rejects existing data. Your
solution design should address whether existing data is revalidated or the
extended code limited by application_id (or responsibility or user).
Libraries have specific size limits, but can have nested calls, as diagrammed.
Segregating code for specific applications may simplify library maintenance
and administration. You can further segregate library code by creating libraries
that address a limited number of forms.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 43

Date Track Considerations


Date Track Considerations
Date Track Forms perform validation / updates
within pre- form logic
Put custom business rules as part of pre- form
event points
3rd party data manipulation can be part of postform logic

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

DateTrack Considerations
Business rule extensions that impact validity of a transaction on datetracked
forms should be associated with a pre event, such as pre-insert, pre-update, or
pre-delete. The extension and form logic need to be coordinated to control
failure or success of the transaction and resulting data integrity. Form logic may
update data before the extension is executed. If your extended logic is at a
post- event, form logic may update the Form Status and change field values
including the effective start date, neglecting the extension logic.
Post event points are useful for performing DML (data manipulation
language, such as update, insert, and delete) statements on tables external to
Oracle Applications, for example, to coordinate an external interface table.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 44

Code Considerations
Code Considerations
Retain Custom Package Specification
AOL Standards: Use FND_ (not Form) Functions
Form Control, Security, Flexfields, Messages

R11i: Use APPCORE2 with CUSTOM library


Library code restrictions
no SQL
Indirect reference

Updates require maintenance

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Code Considerations
Date Track Forms perform validation and updates within pre event
Form logic
Use pre event points for custom business rule extensions
External DML can be part of post form logic
Custom Library is shared among Oracle ERP Applications
Restrictions
Do not change the specification of the CUSTOM package
Use FND_FUNCTION (not CALL_FORM or OPEN_FORM) to call Forms
The only libraries you can attach to CUSTOM are your additional Custom
libraries (not APPCORE, for example, as it would result in a circular reference)
Appcore calls Custom; Appcore2 is a duplicate of Appcore, provided for any
calls from Custom (thus avoiding circular reference).
Forms library standard restrictions, including exclusion of SQL.
APP_ITEM_PROPERTY is not available
Upgrades: you will need to revalidate and test your code to ensure compatibility
with upgrades since form functionality may reflect procedural or processing
changes.
Follow the Oracle Application Coding and User Interface Standards.
Revalidate Custom Library code after an upgrade; reconfirm that it is still
required.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 45

Suggested Business Rule Framework


Suggested Business Rule Framework

Database
Data Model

Form
Batch
Processes

Core HRMS APIs

Hooked Code
CUSTOM
Library

User Defined APIs & PL/SQL


Formula APIs

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Suggested Business Rule Framework


This diagrams where Custom Library fits into the HRMS business rule extended
framework. Recall that some historic Forms do not use APIs, by-passing
Hooked code. However, in those cases, Custom Library remains an option for
accessing Form attributes and extending logic for business rules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 46

Fundamentals
Fundamentals

Oracle Developer Forms


PL/SQL for procedures and functions
Library code and files: .pll and .plx
Profile Option Utilities: Diagnostics
Reference Material

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Fundamentals
Custom Library requires familiarity with several tools, including:
Oracle Forms Developer, ideally AOL Standards
PL/SQL
Library syntax and behavior, including .pll and .plx priority.
Note: ATG (Application Technology Group) references and courses are
available for Extending Oracle Applications.
Diagnostics
If an error arises in a form or procedure that you have extended, remove the
extension and test to confirm normal behavior of the delivered code. This will
assist you in locating the source of error.
Toolbar Help > Diagnostics > Custom Code allows you to toggle the Library off
and on. Toggle Custom Code off to eliminate the call, verifying normal form
behavior. If the error remains when Custom Library is off, then you may have
an issue with the delivered code or form.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 47

Practice: Custom Library


Practice: Custom Library

Follow the demonstration, or use the notes


provided, to extend validation for entering a
person using Custom Library

(N) > People > Enter and Maintain

Copyright Oracle Corporation, 2001. All rights reserved.

Online Help
For details on how to enter a person, please refer to the online Help path :
Oracle HRMS > Workforce Management > Workforce Information Entry >
How to Enter Information Using Windows > Enter a New Person

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 48

Summary
Summary
Having completed this topic you should be able to do
the following with Custom Library:
Describe Custom Library
Describe Usage
Identify Design Considerations

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Summary
You should now have a better understanding of the Custom Library within the
Oracle ERP applications and be able to explain its structure and components.
We have also reviewed possible uses of the Custom Library and have identified
items to consider when planning to use the Custom Library to extend
functionality of the delivered ERP Applications.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 49

API User Hooks

API User Hooks

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 50

Objectives
Objectives

At the end of this topic you should be able to:


Describe API User Hook usage
Identify User Hooks
Implement Extra Logic with User Hooks

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 51

Agenda
Agenda
Definition of User Hooks
Where they fit into HRMS code and processes
Implementing Hooked Code
Identify API and Hooks
Register with Pre-processor

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 52

User Hook Overview


User Hook Overview
Predefined Locations for extra logic
Process: Extra Logic Interrupts core processing
Extra logic will be executed
Raise error prevents core processing
Success continues core processing

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

User Hook Overview


The User Hook feature supports custom business logic extensions to Oracle
HRMS APIs without changing delivered code. You hook logic to one of many
specific and predefined hook points in the API process. Your code is executed
automatically with the associated API.
Scenarios for which you might use hooked code include:
Extending validation of data
Accessing or maintaining data held in external (non-Oracle Applications)
specific tables concurrent with HRMS data entry
Sending alerts from particular events within Oracle HRMS.
User Hooks offer functionality similar to Custom Library, but on the database
server rather than the front end.
You hook user code at locations where extra logic can be executed: the core
HRMS process stops, your extra logic is then executed. The core process
continues if your logic completes without error.
The table HR_API_HOOKS contains all the hooks available for each API
module listed in the HR_API_MODULES table.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 53

User Hook Overview


User Hook Overview
Types of hooks
Legislation-specific logic
Application-specific logic
Customer-specific logic

Extend core product API functionality


Executed automatically from associated API
All user extensions external to delivered APIs

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Types and Features


User Hooks are the only type of API Hook available for customer modification;
other hooked code is restricted. All hooks share the same hook points,
extending functionality for legislation, interfacing with other Oracle
Applications, and custom extensions.
Direct calls to only the published APIs are supported: direct calls to any other
server-side package procedures or functions of the Oracle HRMS product set
are not supported, unless explicitly specified.
Comparison with Legislative and Application Hook Call types:
Criteria for
Criteria
Customer
Call Type Execution
Checked
Modifiable?
Customer Always executed
(Not Applicable)
Yes
Legislation Only when the current
At run-time:
No
business group legislation when API process
code matches.
reaches hook point
Application App. installation
When pre-processor No
status; all business groups runs

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 54

Hook Code Relationship


Hook Code Relationship

Legislation or Customer
Specific Code

Shipped by Core Product


Core Product
API Code

Call Package A

Package Header

Package Header
Package Body

Package Body
Hook Package

Call Package B

Package Header

Package Header

Package Body

Package Body

Built by
preprocessor

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

HR Development Hook to APIs


Understanding the changes that resulted in current hooks helps you to design
effective logic. For example: rather than branching the core code, core
processing checks legislation codes, then executes appropriate hooked code.
This design facilitates upgrades: hooks are regenerated during the upgrade
process. However, note that Oracle reserves the right to change HR schema,
which may require customized PL/SQL to be modified after an upgrade.
Primary User hooks Advantages over Custom Library:
First, the hooked code needs to be implemented in only one place;
whereas Custom Library changes may need to reside in multiple locations.
Second, hooked code is immediately available to all interfaces that call the
API, such as Forms, Self-Service, and Data Pump.
From 11.0.3 forward, user hook code includes flexfield validation; but hooks
cannot support flexfield validation that refers to unavailable fields, such as
context-sensitive fields unavailable to the server code.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 55

Uses of Hooks
Uses of Hooks
Legislation-specific data validation
Maintenance of data held in extra customer-specific
tables
Capture specific business events

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Customer specific data validation


User Hooks can address needs for business rule extensions, such as:
If you must restrict grade changes to a single step but have exceptions for
employees at a specific location, or for employees who have been in a
grade for longer than a specific time period.
If you have tables external to HRMS that you want to access during
specific HRMS entry.
If you want to create events based upon HRMS action and other
complex requirements such as data in external or interface tables: such as
if an employee is leaving the enterprise and you want to send an electronic
message directly to your separate security database.
Delivered hook functionality includes batch creation of SSHR user accounts.
All Oracle HRMS need to be registered with a username, password and a
responsibility. In R11i, a set of concurrent programs and a user hook API have
been created to automate this process.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 56

Implementing: Overview
Implementing: Overview
Identify APIs and user hooks
Identify available data
Implement PL/SQL server-side package
procedure
Register procedure with user hooks
Execute user hook preprocessor

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Implementing User Hooks Overview


When designing hooked code, first analyze your business requirements while
considering the context of APIs and hooks. Registration of the procedure and
running the hook preprocessor complete the implementation. When the API is
called, the hooked code is executed.
Identify APIs and user hooks where you want to attach extra logic. You
need to find the specific API to which your code should be hooked, and to
determine if a hook exists, and exactly which hook to use.
Identify data values available as parameters at the specific user hook.
Implement your logic in a PL/SQL server-side package procedure.
Register: Call hr_api_hook_call_api.create_api_hook_call API, which
registers your package. Define data mapping between the user hook and
server-side package procedure, inserting the procedure in the table.
Execute the user hook preprocessor program. This validates the
parameters to your PL/SQL server-side package procedure and
dynamically generates another package body directly into the database.
This generated code contains PL/SQL that calls the custom package
procedures from the API user hooks.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 57

Implementing User Hooks


Implementing User Hooks
$PER_TOP/admin/sql/hrahkpar.sql lists:
APIs
Hooks
Data Available

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Identify API and Hooks


Implementing hooked code requires you to first analyze your business rule, then
identify the appropriate API, determining if it has hooks. You register your
customized procedure, which is executed when the API is called.
Many forms do not call APIs: the Enter Person Information is one example.
Hooks added to the Create_Employee API will not be executed from the form.
In cases where forms do not use APIs, you extend code in Custom Library. User
Hooks are not provided for utility type APIs, such as
CREATE_MESSAGE_LINE.
A list of each API, associated hooks, and parameters available to hooked
procedures can be obtained by running $PER_TOP/admin/sql/hrahkpar.sql.
Note: It is important to recognize that you can locate code for which extensions
are not supported. For example, we discuss User Hooks because the hook
strategy includes other, off-limit types of hooks. Likewise, there are packages
that appear similar to APIs, but for which extensions or direct customer access
is not supported. Primary reasons for not supporting extensions in such code are
(1) the code may be changed without notice, (2) if you access the code directly,
your upgrades may be compromised, and (3) you may inadvertently
compromise data or process integrity.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 58

Available User Hooks


Available User Hooks
(Business Process) API

Before Process
User Hook

After Process
User Hook

Core Product
Logic

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Hooks in Business Process APIs


All of the User Hook Support scripts are located in $PER_TOP/admin/sql
operating system directory. We noted different types of user hooks, including
two for Business Process APIs: Before Process and After Process.
Before Process runs your code before API validation and database changes are
made; After Process runs only if API validation and database changes are
successful.
Each API has both hooks. For example, if you want additional logic at
employee data entry, first determine whether to use create_employee,
update_person, or update_assignment. Two hooks for each API allow you to
link logic to both a specific API and user hook. Then, select the hook.
API user hooks are provided in the HRMS APIs which create, maintain, or
delete information. For example, the create_employee and
update_emp_asg_criteria APIs. The corresponding alternate APIs, such as
create_us_employee and create_gb_employee, do not have hooks. You
associate extra logic only with the main API.
Once you have identified the API and user hook for your extended logic,
determine which data values available at that point in the process.
$PER_TOP/admin/sql/hrahkpar.sql lists the data available, as well as the APIs
and associated hooks. Hint: it creates a large file; you can spool the output to an
operating system text file.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 59

Create Hook Packages


Execute hrahkall.sql in SQL*Plus to create the hook package bodies for all of
the different API code modules.
Execute hrahkone.sql in SQL*Plus to create the hook package bodies for just
one API code module, such as one main API (or one internal row handler
module). Specify the api_module_id with this script. The required
api_module_id value can be obtained from the HR_API_MODULES table.
Locate Hook Information
The following sql retrieves the hook details of the After Process hook for the
CREATE_EMPLOYEE business process.
SQL> select ahk.api_hook_id,
2
ahk.hook_package,
3
ahk.hook_procedure
4 from hr_api_hooks ahk,
5
hr_api_modules ahm
6 where ahm.module_name='CREATE_EMPLOYEE'
7
and ahm.api_module_type = 'BP --business process
8
and ahk.api_hook_type = 'AP --After (or Before) Process
9
and ahk.api_module_id=ahm.api_module_id

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 60

Available User Hooks


Available User Hooks
Internal Row Handler
either
Core Product
Validation

Core Product
DML

After Delete
User Hook
After Update
User Hook
After Insert
User Hook

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Hooks in Row Handlers


Calls are permitted only to the list of supported and published APIs. Each
release of HRMS includes a guide to New Features (and in Online Help the
Whats New file provides incremental notes) that include a list of supported and
published HRMS APIs.
Core logic components include internal row handler code for each table
impacted by an API, controlling insert, update, delete, and lock processing.
Row handler modules use three user hooks: After Insert, After Update, and
After Delete. The user hook extra logic is executed after successful current table
and column validation, immediately after the corresponding table DML (data
manipulation language) statement.
Direct calls to internal row handlers are not supported; row handlers do not
contain the complete validation and processing logic that Business Process APIs
manage.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 61

Available User Hooks


Available User Hooks
create_employee API

After Process
User Hook

Before Process
User Hook
per_all_people_f
Row Handler

per_all_assignments_f
Row Handler

per_periods_of_service
Row Handler

After Insert
User Hook

After Insert
User Hook

After Insert
User Hook

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Row Handler Hooks


The three types of Row Handler user hooks diagrammed above, perform your
code after performing an insert, update, or delete on a specific table. Main APIs
that update tables call row handlers, executing their hooks. You can produce a
list of Row Handler APIs by querying the module_name from
HR_API_MODULES where the api_module_type = RH (row handler).
The following SQL retrieves hook details for the After Insert hook for the
PER_ALL_PEOPLE_F table.
1
select ahk.api_hook_id,
2
ahk.hook_package,
3
ahk.hook_procedure
4
from hr_api_hooks ahk,
5
hr_api_modules ahm
6
where (ahm.module_name='PER_ALL_PEOPLE_F'
7
or ahm.module_name='PER_PEOPLE_F')
8
and ahm.api_module_type = 'RH'
9
and ahk.api_hook_type = 'AI'
10*
and ahk.api_module_id=ahm.api_module_id

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 62

Available Data
Available Data
Values in API Hooks include API values:
Read-Only
P_<column_name>
NOT: Who_columns, p_validate

Values in Row Handler Hooks


Specific to Row Handler Type

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Available Data
For API hooks, most values in the calling API can be passed as read only to
the user hook custom code. The exceptions are: row Who columns and the
p_validate parameter.
Access API data using standard API parameter naming convention, for
example: p_<database_column>.
Each Row Handler hook has different data available:
After Insert: new column values populated or derived during insert are
available, using p_<database_column> naming standards.
After Update: both new values and old values are available.
Updated values: p_<database_column>
Previous values: p_<database_column>
After Delete: only previous values are available, using the convention
p_<database_column>
Note that previous values are not available on Before Process, After Process,
and After Insert hooks.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 63

Implementing Extra Logic


Implementing Extra Logic
PL/SQL server-side package procedure
As with API calls: No commits or full rollbacks
Error PL/SQL exception

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Extending Logic
You can include any PL/SQL except commit or full rollback. These statements
would interfere with data integrity. The API strategy restricts commit and
rollbacks in hooked code. The hook mechanism will produce an error if a
rollback or commit is attempted in hooked code.
Your code should raise a PL/SQL exception when an error is detected. This
triggers the API mechanism to rollback any database changes in the current call
to the published API, including Before Process hooks.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 64

Implementing Extra Logic


Implementing Extra Logic
Context checking
Legislation Hooks match Business Group
Application Hooks independent of User Hooks
User Hooks: always executed

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Implementing Extra Logic: PL/SQL Procedure


When the API reaches the hook point, the user hook is unconditionally
executed. If you need conditional logic, you must include it in your custom
PL/SQL code.
The following pseudo-code demonstrates setting an application error.
if p_organization_id <> l_organization_region then
dbms_standard.raise_application_error
(num => -20999
,msg => Organization must be in region );
end if;
end organization_range_check;
exit;

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 65

Register Extra Logic


Register Extra Logic
Mapping in HR_API_HOOK_CALLS table
Pre-processor registers calls
Run for one API or all
Registers hook package body
Upgrade automatically calls Pre-processor

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Registering Extra Logic


After writing hook code, you register it, then modify the hook package to call
your code. For the example implementation of an After Process hook in the
CREATE_EMPLOYEE Business Process API, using the hook_call_id and
object_version_number in the call to hr_api_hook_call_api procedures.
Registering the User Hook
You link the custom package procedure to the hook package. The
HR_API_HOOK_CALLS table holds information on hooked calls and
packages. It is maintained by the following three procedures:
hr_api_hook_call_api.create_api_hook_call
hr_api_hook_call_api.update_api_hook_call
hr_api_hook_call_api.delete_api_hook_call
You pass the api_hook_id and hook_type to register a hook for your custom
package. Only package procedures are supported; however, you can add
multiple hooks to each API. Order multiple procedures with sequence numbers,
normally > 2000, since seeded HRMS logic uses sequence numbers up through
2000.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 66

Partial code:
begin
hr_api_hook_call_api.create_api_hook_call
(p_validate
=> false,
p_effective_date
=> to_date('01-JUL2001','DD-MON-YYYY'),
p_api_hook_id
=> 63, --get hook ID
p_api_hook_call_type => 'PP', --pkg.procedure
p_sequence
=> 3000,
p_enabled_flag
=> 'Y',
p_call_package
=> ORGANIZATION_CHECKS,
p_call_procedure
=>ORGANIZATION_RANGE_CHECK',
p_api_hook_call_id
=> l_api_hook_call_id,
p_object_version_number=>l_object_version_number);
end;
Preprocessor
The preprocessor must run before any changes (insert, delete, update) to the
HR_API_HOOK_CALLS table are completed. (That is, hooks are not enabled
by only directly adding rows to the hook_call table). The preprocessor builds
the hook package body, coding any number of calls to the custom package
procedure.
Technical Notes:
The preprocessor runs automatically during upgrades, creating hook package
bodies.
Run the preprocessor using the $PER_TOP/admin/sql hrahkall.sql or
hrahkone.sql in SQL*Plus as user Apps.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 67

Error Handling and Messages


Error Handling and Messages
Trap Errors
capture exceptions early in your logic

Recognize HRMS User Hook Package names


Error messages include the procedure name

Form Errors
Information in Error History

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Error Handling
Errors are displayed with the following syntax:
ERROR at line 1:
ORA-20999: <your custom validation/error message>
ORA-06512: at "APPS.<MY_VALID_CHECK>", line 22
ORA-06512: at "APPS.HR_EMPLOYEE_BK1", line 131
ORA-06512: at "APPS.HR_EMPLOYEE_API", line 504
ORA-06512: at line 21
Running from a form, Error History shows the the following syntax:
FRM-40735: <procedure-name> trigger raised unhandled
exception ORA-20999
First try to identify if an error is a standard Oracle HRMS error. Identify your
custom messages so that text, location, and sequence can be traced easily.
The above example (referencing line 131) identifies the package which reported
the error, HR_EMPLOYEE_BK1, which follows the hook procedure naming
convention.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 68

User Hooks in the Business Rule Framework


User Hooks in the Business Rule
Framework
Database
Data Model

Form
Batch
Processes

Core HRMS APIs

Hooked Code
CUSTOM
Library

User Defined APIs & PL/SQL


Formula APIs

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Business Rule Framework


This simplified diagram shows the relation between delivered code, including
APIs and custom hooked code, and your extended business rules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 69

Practice: User Hook Validation


Practice: User Hook Validation

Follow the demonstration, or use the notes


provided, to create a validation extension
associated with a User Hook.

(N) People > Enter and Maintain

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Online Help
For details on how to access the Person Window please refer to the online Help
path :
Oracle HRMS > Workforce Management > Workforce Information Entry >
How to Enter Information Using Windows > Enter a New Person

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 70

Summary
Summary
Having completed this topic you should be able to:
Describe the uses of API User Hooks
Implement User Hook Calls
Implement Extra Logic into Hooked Calls

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 71

FastFormula Extensions: Database Items

FastFormula Extensions: Database Items

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 72

Objectives
Objectives
At the end of this topic you should be able to explain
the components and setup steps of a Database Item

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 73

Agenda
Agenda
Database Item Definition and Contexts
Components and the Application Dictionary

Designing and Building


Using Database Items

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
FastFormulas are used throughout HRMS, in Assignment Sets, PTO Accruals,
QuickPaint, Magnetic Tapes, Information Elements, and in Oracle Payroll and
Benefit Applications. Formulas reference database items; input values can be
made into database items, delivered create database items from most flexfield
attributes or segments.
Database items are user-friendly handles for complex SQL. You have the option
of extending the power of formulas by creating your own database items when a
specific database item is not delivered or generated in the product.
Formulas, functions, and database items are technical tools that provide power
and flexibility for extending HRMS to handle custom business rules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 74

Overview
Overview
This topic presents components of Database Items
and setup steps for defining a new FastFormula
Database Item

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 75

Database Items and FastFormula


Database Items and FastFormula
FastFormula in HRMS
Magnetic Tapes, Elements, QuickPaint Reports, PTO
Accruals, Assignment Sets
Oracle Payroll, OAB Rules

Used by
Localization teams
Customers
Consultants

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Business Rule applications of FastFormulas


Customers and consultants use formulas to:
Define compensation and benefit processing rules, calculations and
comparisons
Define element input validation
Define payroll element skip rules
Localization analysts and software engineers use formulas to:
Define legislation specific compensation and benefit processing rules
calculations and comparisons
Define legislation-specific element input validation
Define legislation-specific payroll element skip rules.
Database items can be created to extend FastFormula functionality. You will
find database items specific to these applications.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 76

Database Item Advantages


Database Item Advantages

Defined in Application Dictionary


Hide database complexity
Resolve contexts, datetracking, SQL
Provide meaningful names
Performance Efficiency

Wh
y no
t
just
writ
e
SQL
?

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Advantages of Database Items


Database items are critical for easily creating extensions to FastFormula that
access complex data. Contexts involve the most complex data, particularly for
OAB and Payroll. For a simple example, consider using the database item
PER_ADR_LINE_1 or the following SQL:
SELECT ADDR.address_line1
FROM per_all_assignments_f ASSIGN,
per_addresses ADDR, fnd_territories_vl a
WHERE to_date (04-JAN-2000', 'DD-MON-YYYY')
BETWEEN
ASSIGN.effective_start_date
and
ASSIGN.effective_end_date
and
ASSIGN.assignment_id
= 122
and
ADDR.person_id
(+)= ASSIGN.person_id
and
ADDR.primary_flag
(+)= 'Y'
and
to_date ('04-JAN-2000','DD-MON-YYYY')
BETWEEN nvl(ADDR.date_from,to_date('04-JAN2000','DD-MON-YYYY')) AND nvl(ADDR.date_to,
to_date to_date ('04-JAN-2000','DD-MON-YYYY''))
and
a.territory_code (+)= ADDR.country

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 77

Database Items: Application Dictionary


Database Items: Application Dictionary
What you need to know before designing Database
Items:
Each returns only one value
Each has specific contexts
Contexts are limited by Formula type
Formula
Formula Type

Formula

Contex ts

Show Item s

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Application Dictionary
The Application Dictionary contains database item tables. Database Items
always use the contexts of:
Business Group - database item name is unique within business group
Legislation Code
Database items are delivered for specific legislations. If either Business Group
or Legislation Code is not specified, the database item is available across all
values of the context.
Referencing a database item in a formula accesses FastFormula Application
Dictionary, which generates the SQL and PL/SQL, selects the database item
value, and provides error-checking code. Formulas are stored in
FF_FORMULAS_F.
Normally, you do not examine the Dictionary contents. For example, you can
use database items without directly accessing their definition, and when you
define a new element, database items can be generated automatically.
However, if you need to define new database items directly in the Dictionary,
you must also load the associated information. Understanding the relation and
limits of contexts will also help you design and debug custom Formulas,
Functions, and Database Items.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 78

Components of Database Items


Components of Database Items
FF_DATABASE_
ITEMS

FF_USER_
ENTITIES

FF_ROUTE_PARAMETER_
VALUES

Route
Parameter
Value

User
Entity

Database
Item

FF_ROUTES

Also used for


balance definitions
FF_ROUTE_
CONTEXT_USAGES

Route

Route
Parameter

Route
Context

Context

FF_ROUTE_
PARAMETERS

FF_CONTEXTS

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Components
You need to identify contexts, routes, and parameters for any new database
items that you want to create. This simplified diagram explains database item
contexts and parameters; FastFormula tables use the prefix FF_.
FastFormula accesses two values in FF_DATABASE_ITEMS to resolve:

The database item value in the DEFINITION_TEXT column. This name


appears in the SQL SELECT clause.

The USER_ENTITY, which identifies the grouping of one or more


database items that are accessed by the same route.
FastFormula uses the user entity to access the table FF_USER_ENTITIES,
identifying the route. The route is the text of the SQL statement following the
FROM keyword, held in the table FF_ROUTES.
If several user entities use the same route, the route contains one or more
placeholders of the form &U# (where # is a sequence number). Each
placeholder references a parameter in table FF_ROUTE_PARAMETERS.
FastFormula identifies the parameter ID from this table.
The values of the parameters are different for each user entity. Using the
parameter ID, FastFormula accesses the value of the parameter for the relevant
user entity in table FF_ROUTE_PARAMETER_VALUES. Each user entity has
a different set of parameter values, so the text of the route is different for each
user entity.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 79

The route may contain another type of placeholder of the form &B# (where # is
a sequence number). These placeholders reference contexts in the table
FF_ROUTE_CONTEXT_USAGES. FastFormula identifies the ID of the
context from this table, and then the name of the context from table
FF_CONTEXTS.
When you define a formula, you assign it to a formula type, such as Payroll
formulas or QuickPaint formulas. The type of the formula determines the
contexts for which it provides values. This is defined in table
FF_FTYPE_CONTEXT_USAGES.
For example, a QuickPaint formula feeds through values for the contexts
Assignment ID and Date Earned. Thus, when you define a QuickPaint formula,
you can use database items that require the contexts Assignment ID and Date
Earned. However, database items using other contexts in their routes are not
available and do not appear on the list of values.
Contexts are part of the mechanism restricting the database items that a formula
can use. Formulas can use only the database items that are appropriate to the
formula context. If a database item is based on a route that does not require any
contexts (for example, a SELECT from DUAL), then every formula type in the
system can access the database item.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 80

Database Items in FF_ tables


Database Items in FF_ tables
Select TARGET.last_name

Select <database item>

from per_all_people_f TARGET,

from <tables>

per_assignments_f asg
where

where

<TARGET.person_id =

<route parameter> =

asg.person_id>

<&U#>

and <asg.assignment_id and


asg.assignment_type>

and <context>
= <&B#>

= <&B#>

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Selecting the Database Item: FF_TABLES


The SQL statement is held in the FastFormula Applications Dictionary. The
database item is stored in the FastFormula table FF_DATABASE_ITEMS.
In the above code, TARGET.LAST_NAME represents the Database item,
where TARGET is an alias for the table name, in this case, PER_PEOPLE.
The FROM clause of the SQL statement is the formula route, held in the table
FF_ROUTES. The keyword FROM and in this case, the Assignment ID, form
the context of the statement. These are held in the table FF_CONTEXTS.
In cases where there may be multiple occurrences of the route and context,
further definition is held in the FF_ROUTE_CONTEXT_USAGES and
FF_ROUTE_PARAMETER_VALUES tables.
In our example, E is a hard-coded variable, and as the route parameter, it is
held in the table FF_ROUTE_PARAMETERS.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 81

Database Item Contexts


Database Item Contexts
Database Items always use these contexts
Business Group ID - database item name must be
unique within the business group
Legislation Code

HRMS Development Legislative teams deliver


database items specific to legislations

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Contexts
Contexts are predefined in FF_CONTEXTS and should not be changed.
Context values are variable, they are not input, but passed to the formula at run
time.
We noted that business_group_id and Legislation are two contexts for all
database items. In the earlier SQL statement example, the route requires two
contexts: Assignment ID and Assignment Type. Designing a database item
requires that you analyze to determine any other required contexts.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 82

Designing the Database Item


Designing the Database Item
Determine for which Legislations and Business
Groups the item will be available
Identify the actual and complete Select statement
Conditions
Null Value?
Not Exist?

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Null, and Not Found


You must determine whether a Database Items can:
Have a null value - actually have a row returned but the value is null
Not exist - no rows retrieved from the select statement
These features relate to two flags that enable validation:
NULL_ALLOWED_FLAG in the FF_DATABASE_ITEMS table. If the
SQL the database item can return a null value, you set this flag to yes (Y); if
you set the flag to no (N) a null value will result in an error.
NOTFOUND_ALLOWED_FLAG in the FF_USER_ENTITIES table
applies to all the database items in a particular user entity. If the SQL can
return no rows for any of the items, set this flag to yes (Y). If you set the
flag to no (N) and the SQL fails to return a row, FastFormula will report an
error.
Note: If both flags are no (N), provide a default value for the database item.
Note: Do not change a formula to resolve system-generated database item
errors. For example, if a table (such as payroll or basic benefits) holds rates,
an undefined rate returns an error. This forces you to define all ranges and is
a valid business requirement.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 83

Building the Database Item


Building the Database Item
Summary of Steps

Write SQL

Load the Route

Load the related Contexts

Insert User Entity rows

Insert Route Parameter rows

Insert the Database Item

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Building the Database Item:


Overview of components to insert to build your database item :
FF_ROUTES
FF_ROUTE_CONTEXT_USAGES
FF_USER_ENTITIES for each route
FF_ROUTE_PARAMETERS
FF_ROUTE_PARAMETER_VALUES
FF_DATABASE_ITEMS
Note: include WHO columns
1. Write the SQL
Write and test the SQL statement using SQL*Plus to ensure that the statement is
correct and returns only one row for FastFormula to process. Tune your SQL at
this point.
2. Load the Route into FF_ROUTES
the from tables
the where components
placeholders for context values, context usages, routes.
Load the Route into FF_ROUTES: You can do this using a PL/SQL routine.
Wherever possible, use the sequence value for the primary keys (such as
FF_ROUTES_S.NEXTVAL) to populate the table. The route is held in the table
FF_ROUTES as a long data type.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 84

3. Load the Context Usages


The next step is to load contexts into FF_ROUTE_CONTEXT_USAGES, using
the following columns:
Name
Null?
Type
ROUTE_ID
NOT NULL
NUMBER(9)
CONTEXT_ID
NOT NULL
NUMBER(9)
SEQUENCE_NO NOT NULL
NUMBER(9)
Use the current sequence number for the route ID. If you used the sequence
FF_ROUTES_S.NEXTVAL to populate FF_ROUTES, the value for this
sequence is FF_ROUTES_S.CURRVAL.
You can obtain the context ID for the specific formula context from
FF_CONTEXTS. The sequence number is simply the B number.
4. Insert into FF_USER_ENTITIES for each route
Business Group ID
Legislation Code
NOTFOUND_ALLOWED_FLAG
Insert at least one row into FF_USER_ENTITIES for each route, specifying
Business Group ID, Legislation Code, the ROUTE_ID, and the
NOTFOUND_ALLOWED_FLAG.
5. Insert Route Parameters
For each route &U# placeholder, you must insert a row into two tables:
FF_ROUTE_PARAMETERS, sharing the route parameter and
referencing the route value
FF_ROUTE_PARAMETER_VALUES, which contains the actual route
parameter value, and references the user entity
6. Insert into FF_DATABASE_ITEMS
You can now insert the database items. For the example, there are three rows in
the table FF_DATABASE_ITEMS that refer to the same user.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 85

Using the Database Item


Using the Database Item
Now the database item can be referred to by simply
using the name in your FastFormula!
Contexts and Routes are resolved
You have defined where it is available
NOTFOUND flag set to validate

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Sharing the Database Item Components


Consider the example of processing payroll elements for an assignment. Your
formula will select values from element entry tables:
- for a specific assignment
- for a specific element
- within the same date range
In this case, the entries contexts, the assignment, element, and date range, all
may remain the same for all input values of that element.
When the database item requires a change in one of these contexts, the result
negatively impacts SQL performance. You can usually minimize the impact on
processing.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 86

Database Items - Troubleshooting


Database Items - Troubleshooting
Can a database item become damaged or lost?
What causes it? How does it get resolved?
If the Route is not correct

Can I design a function that calls a database item


requiring unavailable contexts? How would I know?
Formula Type determines available Contexts

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 87

Practice: Database Item Components


Practice: Database Item Components

Follow the demonstration, or use the notes


provided, to examine components of a database
item.

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Online Help
For more details on how to create a Database Item, please refer to the
Technical Essay, Defining New Database Items, available on Metalink at:
Technical Libraries > ERP Applications > Human Resource Management
Systems > Human Resources > Documentation > Release 11i
Documentation > Global > Implementing Oracle HRMS > Technical
Essays > FastFormula > The FastFormula Application Dictionary >
Defining New Database Items

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 88

Summary
Summary
In this topic, you should have learned:
The components of database items
How contexts are delivered and used
That you can use the FastFormula Application
Dictionary to create new Database Items

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 89

FastFormula Custom Functions

FastFormula Custom Functions

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 90

Objectives
Objectives
At the end of this topic you should be able to:
Describe the components of a FastFormula
Function
Consider business rules for External Functions
Describe how to register a Function

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 91

Agenda
Agenda
FastFormula Functions: Definition
Components
Delivered Functions
Extensions
Requirements
Setup

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topic
This topic presents FastFormula Functions for an understanding of how
Functions can extend the HRMS application to address custom business rules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 92

FastFormula Functions
FastFormula Functions
PL/SQL Routines that return a single value
Use Forms to Register Functions
Function
Context
Parameters

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

FastFormula Functions
Functions manipulate different types of data in the HRMS Applications, for
different business and technical purposes. For example, specific delivered
functions operate on strings, numbers, or dates, including converting data types.
The following appear and act similar to SQL*Plus functions:

UPPER converts a text string to uppercase

ROUND rounds up or down, numeric data

ADD_DAYS changes the day by the prescribed number of days

NUM_TO_CHAR converts numerical data to a text string.


In addition to the data manipulation functions, business rule functions exist. For
example, validation for national identifier varies with legislation.
Business rules which require complex calculations or validation not
configurable through standard features can be resolved with custom extensions,
which includes FastFormula functions. You define a function in PL/SQL,
identify contexts and IN parameters, and have it return one result. By creating a
function for FastFormula, you can take advantage of database items and the
formula engine to simplify your extension.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 93

Components of a FastFormula Function


Components of a FastFormula Function
FF_FUNCTION_
PARAMETERS

FF_FUNCTIONS

Function
Parameter

Function

Function
Context
Usage

Context

FF_FUNCTION_
CONTEXT_USAGES

FF_CONTEXTS

Copyright Oracle Corporation, 2001. All rights reserved.

Components
The components of a FastFormula function are held in four tables:
FF_FUNCTIONS holds the actual function.
FF_FUNCTION_PARAMETERS holds parameters which are called by the
functions.
FF_FUNCTION_CONTEXT_USAGES defines the contexts used by each
function, determining contexts that are substituted at run time.
FF_CONTEXTS holds the contexts for all of the functions.

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 94

FastFormula in HRMS
FastFormula in HRMS
Formulas: call Functions

QuickPaint
Information Elements
eBI (eBusiness Intelligence) HRMS
Payroll Elements
Benefits Rules

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

FastFormula in HRMS
FastFormula is used throughout the HRMS application. Specific areas are listed
above. In some cases, the generic or template formulas and delivered functions
resolve most business problems. However, exceptional and complex rules may
require extensions to delivered functionality. Some Formulas are designed
specifically for those extensions, such as many of the OAB Rules, which can
augment or replace logic set up in the Forms. Other product components, such
as PTO Accruals and eBI-HRMS, deliver template formulas, with specific
points for business rule extensions.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 95

Delivered Formula Functions


Delivered Formula Functions
Simplify Application Extensions
Get_table_value()
Data Conversion
Mesg = Over the limit by + to_text(amount)

Arithmetic Operations
Total_amount = wages + bonus + expenses
Round ()

Legislative-specific and Product-specific functions


Tax_amounts Balances

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Delivered Functions
Many of the delivered functions are for data and datatype manipulation or
conversion. These functions can be used as building blocks for extensive logic.
In contrast to procedures, functions return one value.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 96

Business Requirements
Business Requirements
You may require a unique function to perform:
- iterative calculations
- format validation
- ???

hy? ?
W
t
Ho
a
w?
h
W

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Business Requirements
Requirements to check external tables or custom conditional format validation
may be easily configured in a formula with an external function.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 97

Custom Functions
Custom Functions
Formula function as custom PL/SQL
You determine

where it is used
which contexts it uses
parameters it processes
datatype it returns

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Formula Functions
When you create the actual package function, list the contexts and then
parameters in the package header. However, when your FastFormula calls the
function, you pass only the parameters through the formula.
You can associate both contexts and parameters with Formula Functions. You
use the application forms to identify your new custom external function, and the
associated contexts and parameters.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 98

Design and Limitations


Design and Limitations
FastFormula Contexts
Database Items
Functions

Examine FF_CONTEXTS and FF_ROUTES to confirm


that your design is valid

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Design and Limitations


It is important to realize that your extensions to database items, formulas, and
functions are all limited by the contexts associated with formula types. The
drivers for limitations are programmatic, business rule, or legislated, and
logical. HR Development sets contexts for formula types, and those cannot be
changed; serious data integrity and upgrade issues would result from tampering
with delivered contexts.
If a context is not available, you may need to include that logic in your external
function.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 99

Setup Formula Functions


Setup Formula Functions
Create new PL/SQL function: Define Function
Window
Register External Function
Enter context usage information: Contexts Window
Enter parameters
Code the details

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Steps to Set Up a User-Defined Function: Define and Register


Define the logic and write the PL/SQL. Your function can use only IN
parameters and cannot use commit, rollback or savepoint statements. You
should list contexts first in the function header. Then list the parameters: only
parameters need to be used in calls to the function from FastFormula; the
Formula will resolve contexts.
Your function needs to be defined with a unique name, in the format
<package_name>.<function_name>
Register your function in the Define Function window, including the function
class as External. The return value is the result of your function, a text, numeric,
or date value. You may also enter contexts and parameters.
Technical Note
Delivered functions often address legislative requirements. Formula Functions
may be required for benefit eligibility or payroll business rules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 100

Practice: Creating a Function


Practice: Creating a Function

Follow the detailed steps, or use the notes


provided, to create a Function

(N) Other Definitions > Formula Functions

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Online Help
For details on how to access the Define Function Window please refer to the
online Help path :
Oracle HRMS > Oracle FastFormula > Formula Reference >
User-Defined Functions

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 101

Summary
Summary
Having completed this topic you should be able to:
Describe FastFormula Function Components
Identify Function Contexts
Describe how to register a Function

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 102

Calling Formulas from PL/SQL

Calling Formulas from PL/SQL

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 103

Objectives
Objectives
At the end of this topic you should be able to
identify how to call FastFormulas from PL/SQL

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 104

Agenda
Agenda

Formula Requirements and Framework


Formula Engine Interfaces
Engine Processes
Server Calls
Design Considerations

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This topic introduces you to the FastFormula Engine, which is accessible from
PL/SQL. This is not a topic in FastFormula or PL/SQL, but designed to suggest
the option of using the Formula Engine an Application extension for handling
your exceptional business rules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 105

Business Requirements for Formulas


Business Requirements for Formulas
Formulas used throughout HRMS
Formula Engine allows you to define Formulas
accessible from
Custom defined APIs
Core Application APIs
Application Forms
Other Application Interfaces

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Business Requirements
FastFormulas replace complex SQL by features that include contexts and input
values; they resolve datetracking, provide validation, process options, messages,
and return values. Oracle HRMS including Oracle Payroll and OAB use them to
define calculations, evaluate conditions, and to validate inputs. They can access
database items, input values, balances, and global values with a simple syntax.
Delivered Formula usage includes pay value calculation, element input value
validation, assignment sets, QuickPaint reports, magnetic tape formatting. In
many localizations, legislated formulas are delivered. You can identify the
generated PL/SQL formulas in the database as: FFP_<Formula Id>_<Effective
Date>
All Formula usage is enabled by the FastFormula PL/SQL engine, which is
accessible through PL/SQL. Examples of where you can run the Formula engine
to extend your business rules include:
Core Application APIs via API User Hooks
Application Forms by use of Custom Library
Other Application interfaces, such as ADE or custom interfaces.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 106

Formulas in Business Rule Framework


Formulas in Business Rule Framework
Database
Form

Data Model

Batch
Processes

Core HRMS APIs

Hooked Code
CUSTOM
Library

User Defined APIs & PL/SQL Formula APIs

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

The Business Rule Framework


This recommended business rule framework demonstrates how Formulas fit into
the extensible features of HRMS. The execution engine files are stored in
$FF_TOP/admin/sql
ffexec.pkh and ffexec.pkb
Server side execution engine package header and body files.
ffcxeng.pkh and ffcxeng.pkb
Multiple User Hooks are predefined at many business process points, so that
you can attach a rule before or after the process. Application forms access
Custom Library, where you can attach many types of rules, including calls to
Formula.
Detailed Reference
For further details, please refer to the Technical Essay, Calling FastFormula
from PL/SQL, available on Metalink at:
Technical Libraries > ERP Applications > Human Resource Management
Systems > Human Resources > Documentation > Release 11i Documentation >
Global > Implementing Oracle HRMS > Technical Essays > FastFormula >
Calling FastFormula from PL/SQL

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 107

Execution Engine
Execution Engine

An execution engine lets you interface to


Formula directly from PL/SQL
Preferred
Server side interface

Available
Client side interface

PL/SQL

output
Formula
Engine

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Server side interface


The server-side interface provides maximum flexibility with relatively low
network demand. This preferred option requires PL/SQL V2.3 or higher.
Package name is FF_EXEC.
Four key stages
PL/SQL table data structures
Client side interface
The client-side interface options workaround Forms4.5 PL/SQL V1 limitations;
this option may be backported for R10.7.
Package name is FF_CLIENT_EXEC and has three variations:
1. Server-Like Interface
Initialize formula (INIT_FORMULA)
Initialize formula inputs (SET_INPUT)
Run formula (RUN_FORMULA)
Retrieve formula results (GET_OUTPUT)
2. Client and Formula ID: single procedure RUN_ID_FORMULA
3. Client and Formula Name: single procedure RUN_NAME_FORMULA

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 108

Overall Process
Overall Process
1

fnd_session

inputs/outputs

6
loop inputs

loop outputs

run formula

ff_exec.init_formula

starts engine

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

1. DateTrack
Insert into FND_SESSIONS to set effective date.
2. Populate input and output tables
Enter each parameter, followed by all necessary contexts. Enter the output
values. Specify the data type for all input and output values.
3. ff_exec.init_formula
Start the engine for a selected formula: the engine is setup with: effective date,
input and output parameter names and data types, and contexts.
4. Loop through custom inputs
Convert parameters: in, out, cache database items. Your PL/SQL code can
identify a number of iterations for the formula, changing the actual values of
any of the previously identified input parameters.
5. ff_exec.run_formula -run specific formula
This call actually runs the formula, processing values you entered into the
inputs. You may have entered one set of values, or coded a loop in PL/SQL.
6. Loop through outputs
After the formula executes, retrieve output values. If you entered input values in
a looping procedure, output values are retrieved similarly.
Example
For classroom discussion and further reference, the following example is taken
from the Technical Essay, Calling FastFormula from PL/SQL available in the

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 109

HRMS Implementation Guide on Metalink at Technical Libraries > ERP


Applications > Human Resource Management Systems > Human Resources >
Documentation > Release 11i Documentation > Implementing Oracle HRMS >
Technical Essays > FastFormula.
The following examples assume we are going to execute the following formula.
Note that the DATABASE_ITEM requires an ASSIGNMENT_ID context.
The formula itself does not represent anything meaningful, it is for illustration
only.
inputs are input1, input2 (date), input3 (text)
dbi = DATABASE_ITEM
ret1 = input1 * 2
return ret1, input2, input3
The following anonymous block of PL/SQL could be used to execute the
formula. In this case, it is called a number of times, to show how we can
execute many times having initialized the formula once.
declare
l_input1 number;
l_input2 date;
l_input3 varchar2(80);
l_assignment_id number;
l_formula_id number;
l_effective_date date;
l_inputs ff_exec.inputs_t;
l_outputs ff_exec.outputs_t;
l_loop_cnt number;
l_in_cnt number;
l_out_cnt number;
begin
Set up some the values we will need to exec formula.
l_formula_id := 100;
l_effective_date := to_date(06051997, DDMMYYYY);
l_input1 := 1000.1;
l_input2 := to_date(01011990, ddmmyyyy);
l_input3 := INPUT TEXT;
l_assignment_id := 400;
Insert FND_SESSIONS row.
insert into fnd_sessions (
session_id,
effective_date)
values (userenv(sessionid),

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 110

l_effective_date);
Initialize the formula.
ff_exec.init_formula(l_formula_id, l_effective_date, l_inputs, l_outputs);
We are now in a position to execute the formula.
Notice that we are illustrating here that the formula can
be executed a number of times, in this case setting a new
input value for input1 each time.
for l_loop_cnt in 1..10 loop
The input and output table have been initialized. We now have
to set up the values for the inputs required. This includes
those for the inputs are statement and any contexts.
for l_in_cnt in l_inputs.first..l_inputs.last loop
if(l_inputs(l_in_cnt).name = INPUT1) then
Deal with input1 value.
l_inputs(l_in_cnt).value :=
fnd_number.number_to_canonical(l_input1);
elsif(l_inputs(l_in_cnt).name = INPUT2) then
Deal with input2 value.
l_inputs(l_in_cnt).value :=
fnd_date.date_to_canonical(l_input2);
elsif(l_inputs(l_in_cnt).name = INPUT3) then
Deal with input3 value.
l_inputs(l_in_cnt).value := l_input3;
no conversion required.
elsif(l_inputs(l_in_cnt).name = ASSIGNMENT_ID) then
Deal with the ASSIGNMENT_ID context value.
l_inputs(l_in_cnt).value := l_assignment_id;
end if;
end loop;
ff_exec.run_formula(l_inputs, l_outputs);
Now we have executed the formula. We are able
to display the results.
for l_out_cnt in l_outputs.first..l_outputs.last loop
hr_utility.trace(output name : ||
l_outputs(l_out_cnt).name);
hr_utility.trace(output datatype : ||
l_outputs(l_out_cnt).datatype);
hr_utility.trace(output value : ||

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 111

l_outputs(l_out_cnt).value);
end loop;
end loop;
We can now continue to call as many formulas as we like,
always remembering to begin with a ff_exec.init_formula call.
Note: There is no procedure to be called to
shut down the execution engine.
end;
/

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 112

Engine Processes
Engine Processes
Refer to package header information
ff_exec.init_formula
ff_exec.run_formula

Logging Options
Enable logging with ff_utils.set_debug

Copyright Oracle Corporation, 2001. All rights reserved.

Engine Processes
Refer to package header information in:
ff_exec.init_formula
ff_exec.run_formula
Logging Options
Enable logging with ff_utils.set_debug.
routing
debug
cache
dbi cache
mru - most recently used formula chain
io_table debug
Note: Documentation available
$FF_TOP/admin/sql
ffexec.pkh
ffexec.pkb

&
l
a

y
l
n

O
e

I
A

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 113

Design Considerations
Design Considerations

Interface to access Formula


Commit logic and Custom Library Events
DateTrack
In / Out Parameters
Contexts
Data types

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Design Considerations
The design of your formula is affected by the interfaces from which it will be
accessed.

Custom defined APIs

API User Hooks

Applications Forms:

Using Custom Library

Directly from within the form
Discussion: Business Rule Example
Presuming your implementation has a scenario that includes a Descriptive
Flexfield on the Assignment, a single segment (Attribute1), Car Entitlement.
Values for this flexfield vary with the employee age and assignment status, and
are updated or verified with the assignment record is accessed in the
Application Forms or when a person is loaded in through an ADE interface
using the API.
Cautions:
Your logic should handle all possible combinations and results.
Check column types and date format.
When using Custom Library to call Formula PL/SQL that references
database items, the value field in the Formula PL/SQL procedures is
VARCHAR2.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 114

All input and output names must be in uppercase.


When calling Formula PL/SQL validation from Application Forms using
Custom Library, note that if a database item is changed in the form fields,
both the Form and your Formula may access the same tables.
Input / Output
You need to define Input and Output parameters in table structures.
Inputs include any parameters required in the formula
Inputs also include any contexts required by the formula
The formula passes and accepts the inputs and outputs as text data types.
Conversion is required, the most efficient conversion functions are:
date_to_canonical
number_to_canonical
Two date data types as of R11i for the contexts:
DATE_EARNED
BALANCE_DATE
Be aware of:
P_USE_DBI_CACHE parameter
Database item details
Index values
Your own server side formula
Logging options for detailed debugging.
Technical Note: Design
Before designing your code, investigate the P_USE_DBI_CACHE
parameter.You need to understand how Form commit logic works and that
calling a Formula PL/SQL routine that references database items through the
Custom Library may have results inconsistent between database and forms.
The P_USE_DBI_CACHE parameter is set to TRUE by default. Therefore you
want to initialize the formula and set the variable to FALSE before checking
your database values. This allows you to capture changes resulting from form
field changes.
Hints: Investigate contexts and routes for database items.
Index values for input and output data structure tables may not always start at 1
so use first and last to be sure of getting the index value you require.
Consider writing your own server side formula wrapper procedure to call
your specific formula. This wrapper can then be called by any type of interface
(for example, Form, batch process).
Debug Logging Options
Logging options for detailed debugging include:

Using HR Trace and PYUPIP utilities

Logging options set using FF_UTILS.SET_DEBUG

Different debug levels:

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 115

1 : FF_UTILS.ROUTING Functions & Procedures Accessed


2 : FF_EXEC.FF_DBG ** not currently used
4 : FF_EXEC.FF_CACHE_DBG Currently executing formula
8 : FF_EXEC.DBI_CACHE_DBG DB Items held in cache
16 : FF_EXEC.MRU_DBG Most recently used formula chain
32 : FF_EXEC.IO_TABLE_DBG Input & output table contents
Considering Contexts
Consider how a context differs when calling a formula from PL/SQL than when
writing a formula within predefined features:
When you call a formula from PL/SQL, you need to pass the context
values to the formula.
When you use a formula in a predefined feature, the context values are
available corresponding to the formula type.
Consider what is consistent about contexts:
The context_id is always limited by the type of formula.
Specific contexts are required for specific database items.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 116

Summary
Summary
Having completed this topic you should be able to
call the FastFormula Engine directly from PL/SQL
and consider business requirements.

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 117

Forms Configurator

Forms Configurator

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 118

Objectives
Objectives
After completing this topic, you should be able to
describe the Forms Configurator and People
Management Templates, including:
How to access them
Identify what you can configure
Identify advantages of using template

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 119

Agenda
Agenda
Forms Configurator and Templates
Template Windows
Features

Using Templates

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This Introduces HRMS Forms Configurator and People Management
Templates. These tools address some needs for Form variations; results can be
combined with other described extensions and with System Administration
features, such as Taskflow. Forms Configurator documentation includes
complete details of fields and instructions. This introductory topic continues the
presentation of HRMS extension options; it does not attempt to address all
documented features.
References
Please refer to the online Help path:
Oracle HRMS > Configure Oracle HRMS > Forms Configurator
Related Metalink documents: Oracle HRMS Family Pack (Whats New in
Release 11i) and Forms Configurator and People Management in Technical
Libraries > ERP Applications > HRMS > Human Resources > Documentation >
R11i Documentation > Global.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 120

Forms Configurator
Forms Configurator
Business Requirements
Multiple Roles
Role-specific Fields

Functions and Extensions


Group, Order, Hide Fields
Event-based Query
Workflow Notifications

Security

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Forms Configurator
Forms Configurator, like Custom Form, is a delivered tool that enables you to
configure and administer Forms changes without coding. Unlike other features,
such as Custom library, the Forms Configurator provides a graphical userinterface to Forms Developer features, HRMS System Administration
Taskflow, and Oracle Workflow notifications.
HR Events, such as job or grade change, are delivered for use with the graphic
timeline. You can also add events to the LOV by using FastFormula to enable
DateTrack History on a field.
Configuration Options include:
Grouping fields onto tabbed areas: group fields for entry or logically
Removing or positioning fields, including some flexfields
Setting field length configure visual attributes
Defining fields as required by business rule
Defining default field values reduce data entry
Adding checklists create a region for data entry, create another tab to
access a checklist of activities for the process or transaction
Create private or public folders maintain frequent queries and data
Taskflow by adding buttons configure and simplify business process
Add Workflow Notifications some messages are seeded

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 121

DateTrack History: Provide graphic timeline for employee and applicant


events.
Security
Configured templates are associated with a responsibility, and to the
corresponding security profile. The same security as in the core HRMS
applications is enforced by limiting data that can be updated in templates.
Security can be enforced by setting the Secured Flag to Y and hiding the
security flag field from the template user.
However, an unsecured mode is available, when enabled by the implementor
or administrator of the template by setting Secured Flag to N: this mode
allows a query to return a list of all people in the query, even though secure and
sensitive HRMS data cannot be viewed or updated for those people external to
the security profile.
Limitations
Professional Interface Forms must be used for complex maintenance, such as
retroactive changes, impacting multiple rows; Template updates and corrections
affect only the latest row.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 122

Template Administration
Template Administration
Use Templates for Top Level in Taskflow
Template Advantages include Support and Upgrade
features

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Template Administration
It is recommended that you copy the delivered templates as a basis for
configuring additional forms for various roles or users.
Upgrades are an important consideration: using predefined templates gives the
advantage of updating only the template during an upgrade; your configuration
is retained as an extension.
In addition to the functionality specified on the previous page, your design can
reflect configuration by:
Choosing the windows and their display order.
Determine tabs, fields, field position and order, and buttons for each
window.
FastFormula for defining right-click information on a field or button.
Context-sensitive fields, including Person Type and Flexfields.
Security restrictions, such as Employees only or Applicants only.
Using predefined lookups: CHECKLIST_ITEM and
CHECKLIST_STATUS, building checklists for business rule compliance.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 123

Using Templates
Using Templates
Generic People Management Templates
Entering Employees PER_ENTER_EMPS
Maintaining Employees PER_MAINTAIN_EMPS

Competencies
Element Entries
Salary History
Contacts

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Using Templates
Templates are provided for specific localizations such as US or UK.
At the time of writing, the delivered templates include:
PER_HIRE_APPS hire applicants
PER_HIRE_EMPS hire employees
PER_MAINTAIN_EMPS maintain employees
PER_GLB_VISA global visa administration.
Other than, PER_GLB_VISA, there are global versions, and localized versions
for, US, UK, Italy, Japan, and Belgium.
Business Processes
The predefined templates relate to business processes, such as hiring a person or
creating an applicant. You can use the Configurator to collect fields from
multiple windows into one window, grouped to reflect your business rules.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 124

Template Windows
Template Windows
Each Template has:
Find
Maintenance
Summary
Data Organizer

Notifications
Help

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Find Window
The Find window is also configurable: you can specify the search fields and
their order. Find options include a simple and advanced Find. The advanced
Find allows partial values and relational operators.
The Find window remains visible and returns values in the lower portion of the
window. You can also configure the display layout for the Find results.
Maintenance Window
The Maintenance window refers the primary template window that you
configure with tabbed regions, field order, and other details.
Summary and Data Organizer
The People Management template provides a Summary window, the Data
Organizer. When the user can expands the Data Organizer node for a person,
the employee and applicant assignments are listed. You define user-friendly
names for assignments. You can use delivered fields, or formula results and
database items to override default field values in this window.
Help
Help refers to delivered templates; you can configure it to your new forms.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 125

Template Features
Template Features
Single-row Flexfields
Context Sensitive Information

Multiple-row Flexfield
SIT
EIT

Folders

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Template Features
SITs and EITs can be added to Template window.
Notification messages can include predefined tokens, including :
HIRE_DATE
FULL_NAME
PER_EFFECTIVE_START_DATE
TITLE
FIRST_NAME
LAST_NAME
EMPLOYEE_NUMBER
APPLICANT_NUMBER
NATIONAL_IDENTIFIER
A complete list of available tokens is available in the Online Help. In addition
to the predefined tokens, you can create tokens using FastFormula.
You can override the default context-sensitive help to display a different target,
using the syntax form.window_name.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 126

Template Features
Template Features
DateTrack History
User Checklists not transactional
FastFormulas for
Assignment Information
Validation
Messages

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

DateTrack History
DateTrack history on template fields by indicating Yes in the DateTrack History
segment on the field flexfield, which results in including the field in the
Timeline LOV and in history being accessible from a right-click list.
User Checklists
You can define User Checklists to track up to 10 tasks for each business
process; lists can include status, date due, date achieved, and task notes. You
can configure checklists for both the Summary and Maintenance windows.
You can also extend Checklist functionality by adding the window directly in a
taskflow, enabling it from certain other windows. The Checklist window itself
is not configurable, but gives users access to any checklist item.
FastFormulas are enabled for templates:
Formula type: Template Information; the value in Assignment_name fills the
Assignment field in the template
Formula Type: People Management Message; to create a message, name the
formula the same as the message that uses its returned token.
Formula Type: Template Information accepts up to 5 input values, returns a text
value in Message, which you associate on the Information Formula property
of a template field. That association makes the value in Message available when
the user right-clicks on the field.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 127

Validation Formula accepts up to 5 input values, and can return 3 values,


including: Status of s for success, Message with a text value, and Item with a
value to replace the field value. Associate the formula with the field by
including the name in the Validation Formula Property on the template field.
Workflow with Notification Messages
Workflow notifications using seeded messages; you can also provide multiple
forms for a sequential process, having multiple people or roles collaborate on a
transaction or approval. Delivered functionality for applicants includes an
automated flow with various Actions, such as:
Offer to Applicant
Applicant Accepted
Hire Applicant
Terminate Applicant
New Application

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 128

Using the Templates


Using the Templates
Applicant Tracking
Hiring
Legislations
US
UK
Global/Generic

Enabled Flag

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Using the Templates


Define your new form based on one of the delivered templates, such as the
legislative version of Applicant Tracking or Hiring a Person, if appropriate.
When you position or add Fields, change labels, and define other field
characteristics, your Field attribute changes are reflected in the designer.
Configured forms can use delivered notifications or new notifications that you
define in Oracle Workflow.
The Enabled Flag controls whether the form is actually available.
You can use Custom Form to specify additional business rule details, such as
limit form data or functions; other extension options are available too.
Define the new form in the Forms Functions Window, to add it to a menu or
taskflow for user access; enter the template name as a parameter.
Note: Complete instructions for Form Function setup are included in:
Oracle Applications Users Guide > Library > Applied Technology >
Oracle Applications System Administration > Function Security > Form
Functions Window.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 129

Practice: Configuring a Template


Practice: Configuring a Template

Follow the demonstration, or use the notes


provided, to configure a People Management
Template

(N) Security > People Management Configurator

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Online Help
For details on how to access Designer(People Management), please refer to the
online Help path :
Oracle HRMS > Workforce Management > Workforce Information Entry >
How to Enter Information Using Templates > Enter a New Person

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 130

Summary
Summary
Having completed this unit you should be able to:
Describe HRMS Forms Configurator
Identify the People Management Templates
Configure Templates

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Summary
You should now have an introduction to the HRMS Forms Configurator and
People Management Templates. You should also be able to explain the
interface and identify some components.
For more information on using Forms Configurator and the People Management
Templates, refer to the Online Help path:
Oracle HRMS > Configure Oracle HRMS > Configure Windows >
Forms Configurator

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 131

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Business Rules in HRMS


Chapter 13 - Page 132

Extending Security
Chapter 14

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 1

Extending Security

Extending Security

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 2

Objectives
Objectives
Identify how to Extend Security Profiles using SQL
Where
Discuss

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 3

Agenda
Agenda
Review of Security Model
Security Profile and Secure Lists

Extension Components and Options


Extending Where in Security Profiles

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Topics
This unit reviews security components, recalling Security Profiles and
Responsibilities; it then reviews Security Lists, which are affected when you
extend the security definition with a custom clause.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 4

Review: HRMS Security Components


Review: HRMS Security Components
Securing data by row, column, function is
accomplished in HRMS by components that
include:
Security Profile
Security Group
Responsibility

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Security Review: the Context for Extending Security


The security toolset builds row and column security by relating to the functional
relations in the core application configuration: organization, positions,
supervisors, and payroll definitions are required when you want to configure
security by those entities.
Security Profile and Responsibility: Limit Rows and Columns
When a user selects a responsibility to access the applications, the associated or
selected security group identifies the security profile. Recall that the security
profile restricts by row; the responsibility components include the menu
structure, which limit the columns.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 5

Restricted by Row and Column


Restricted by Row and Column
Responsibility plus Security Profile

Last Name

First Name

Emp
Organization Salary
Number
1000
East
$ 55,000.00

Davis

Audrey

Greaves

Jodi

1020

East

$ 83,000.00

Krolczyk

Richard

1040

West

$ 64,000.00

O'Connor

Patrick

1060

West

$ 59,000.00

Presley

Bryant

1080

West

$ 75,000.00

Salvatore

Angela

1090

South

$ 99,000.00

Sweeney

Dan

1100

South

$ 44,000.00

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Sensitive HRMS information is held in Secure Tables


HRMS owns the secure tables to which Apps has access. This means that when
connect directly to the APPS Oracle User through SQL*Plus, you have
unrestricted access to the HRMS tables. But if you connect as an HR reporting
user, your access is restricted according to your security profile.
Security Profile and Responsibility: Limit Rows and Columns
In this example we apparently see:
Rows limited by organization security;
Columns, including Salary, limited by the responsibility.
Access Consideration
You can duplicate Oracle Applications session security by calling
FND_GLOBAL.APPS_INITIALIZE with the IDs of the user, responsibility,
application, and security group to simulate a signon session. The
security_group_id defaults to zero (that is, to the setup Business Group).
Note: FND_GLOBAL is not accessible by HR reporting users.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 6

Security Components: Lists and Views


Security Components: Lists and Views
Lists Populated by LISTGEN
Referenced by Secure Views through the
HR_SECURITY package
PER_PERSON_LIST

PER_POSITION_LIST
PER_ORGANIZATION_LIST
PER_PAYROLL_LIST
PER_PERSON_LIST_CHANGES*

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Security Lists
Your Security Profile Window selections define which rows are built into these
_LIST tables. You can make changes in the window at any time, but you must
run LISTGEN to effect changes in the Applications.
The Custom Security Extension we discuss impacts the Security Lists: you can
further limit the security definition by adding to the where clause in defining
the Security Lists. This allows you to define security based upon actual values
of additional entities, for example.
Additional Notes
Supervisor security and any custom security impact PER_PERSON_LIST; this
table contains only current employees and applicants.
The last table, PER_PERSON_LIST_CHANGES is populated at
employee/applicant termination, so their data remains visible.
Employee and Applicant data is the target of HRMS Security. Person data for
persons with system type Other are not restricted.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 7

Security Profile
Security Profile
Security Profile = Security List x Secured Tables
LISTGEN Builds Security List for each Security
Profile by traversing setup and security
configuration:

View All?
Payroll
Organizations
Position

Person +

Copyright Oracle Corporation, 2001. All rights reserved.

Security Profiles
Security Profile Lists are intersection tables between a Security Profile and
HRMS Secured Tables; the tables and corresponding columns include:
PER_PERSON_LIST
SECURITY_PROFILE_ID, PERSON_ID
PER_POSITION_LIST
SECURITY_PROFILE_ID, POSITION_ID
PER_ORGANIZATION_LIST
SECURITY_PROFILE_ID, ORGANIZATION_ID
PAY_PAYROLL_LIST
SECURITY_PROFILE_ID, PAYROLL_ID
PER_PERSON_LIST_CHANGES
SECURITY_PROFILE_ID, PERSON_ID

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 8

Building the Profile


Recall that you need to explicitly set HR:Security Profile option at the
Responsibility level; the value is Standard in Standard security, but it is one
of the Security Groups when you have the Security Group Enabled profile
option selected.
The HR:Business Group profile is derived from the Security Profile ('Standard')
in Standard security, or when the user selects both a Responsibility and a
Security Profile in a Security Group Enabled model.
When a Security Profile is View All, there are no Security List limitations.
Similarly, if All Payrolls are included, there is no limit entered for payrolls;
however, if payroll security is defined, those limits are entered into
PER_PAYROLL_LIST.
Organization security always includes the Business Group, regardless of the
top organization selected (or the top level in an organizational hierarchy). An
employee or applicant is associated with the Business Group by default (or
default assignment) at entry, and must remain accessible from the Business
Group level until associated with another organization with an assignment
update.This means that in most cases you do not want to classify your Business
Group as an HR Organization, but create a lower organization to hold
employees.
The Position List builds upon any organization limit, by definition.
The Person List depends on the earlier versions of above Lists, including both
existing current assignments and any future new hires, but not ex-employees
who have future hire dates. Supervisors and Custom extensions impact this list.
As noted earlier, people who do not have assignments (system person type
Other) are available in every Security Profile.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 9

HR Security Profiles

HR Security Profiles
APPLSYS

APPS

HR
PER_ALL_
PEOPLE_F

FND_
SESSIONS

FND_
SESSIONS

USER1

synonym

table

table

PER_PERSON
_LIST

Select * from
per_people_f

LISTGEN

table

Define
Security
Profiles

PER_SECURITY_
PROFILES
table

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

LISTGEN and Security Profiles


Definitions in the Security Profile window result in updates to
PER_SECURITY_PROFILES table.
LISTGEN is the process that updates PER_PERSON_LIST.
Person_id is provided by Per_All_People_F table owned by HR
Per_Person_List table uses person_id, security_profile_id
Per_Security_Profiles table uses security_profile_id and
reporting_oracle_username.
Debug Tips
Verify that LISTGEN has been run successfully, updating the security tables.
If you do not see correct data in the Application Forms, check the Secure Views
in SQL*Plus. Since the Apps user has View All security, set the Security Profile
and Business Group using FND_GLOBAL.APPS_INITIALIZE using
parameter values for the appropriate user and security profile. Then check the
_LIST tables, such as PER_PERSON_LIST.
PER_PERSON_LIST_CHANGES, not in this diagram, identifies employee and
applicant terminations.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 10

Extending Security
Extending Security
Security List
WHERE

Define in Security Profile Window


Run LISTGEN
Table: PER_PERSON_LIST

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Custom Security Restrictions


We have noted that your changes in the Security Profile Window impact the
PER_PERSON_LIST when the LISTGEN process updates the tables.
When you enter a condition as part of the Where clause in the Custom field,
your syntax is immediately validated. When LISTGEN runs, your custom
extension is added to the security profile, further defining the employees and
applicants for the Security Profile.
Possible business rule extensions could be based on values such as:
Assignment Status permitting access to only active employees or
employees on a specific leave.
Employment Category permitting access to only part-time employees.
Location limiting access to list employees at a particular location.
Note that Custom extension adds to entity values identified in the Security
Profile Window. For example, limiting by Location would further restrict
employees and applicants in a Security Profile that includes Organization or
Organizational Hierarchy.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 11

Practice: Custom Security Profiles


Practice: Custom Security Profiles

Follow the demonstration, or use the notes


provided, to extend a Security Profile with custom
code

(N) Security > Profile

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Online Help
For details on how to access the Security Profile window, please refer to the
online Help path:
Oracle HRMS > Security > How to > Define a Security Profile.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 12

Summary
Summary
Having completed this unit you should be able to:
Recall the Security Model including the Security
Profile and Secure Lists components
Know how to Extend Security Profiles with a
Custom Where

Copyright Oracle Corporation, 2001. All rights reserved.

y
l
n

Summary
For details on how to extend Security, please refer to the Technical Essays,
Security Profiles and Security Processes, both available on Metalink at:
Technical Libraries > ERP Applications > Human Resource Management
Systems > Human Resources > Documentation > Release 11i Documentation >
Global > Implementing Oracle HRMS > Technical Essays > Extending Security
in Oracle HRMS > Extending Security in Oracle Human Resources.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 13

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security
Chapter 14 - Page 14

Extending Business Rules in


HRMS Demos and Practices
Chapter 15

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 1

Extending Business Rules in HRMS Demos and Practices


Job Title*
The Job Title [list@YourCompany.com?Subject=EDUxxxxx] is responsible for ensuring that
this document is necessary and that it reflects actual practice.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 2

Practice: Custom Library


Instructor Demonstration and Practice
The objective of this demonstration and practice is to allow you to extend validation on
employee data entry by use of Custom Library.
Given a scenario that data entry inconsistencies include employee names entered in all uppercase You want to add validation to alert the user when the name is entered in upper-case.
Specifically, your code should execute conditionally for the Form, Block, and Event(s).
Additionally, limit the code by the HR application_id (800) and the unique suffix for your data
entry (where xx is your team number).
Include your business rule code in Custom library.
For classroom purposes, test your rule by entering an employee with a unique suffix that
identifies your team number.
If you choose to create a solution for an alternate business rule, first verify with your instructor.
Technical Note
Please see additional notes for including supporting libraries if using custom.pll on your desktop.
This can be used for testing a form running on your client.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 3

Custom Library Solution


Instructor Demonstration and Practice Solution
1. Instructor only: Backup the existing CUSTOM.pll: log in to your server, such as Unix,
using the instructor ESS reference for a Telnet session host, user, and password.
2. Instructor: Locate the library in $AU_TOP/resource
3. Instructor: Copy the file: cp CUSTOM.pll CUSTOM_old
4. Access the library from your desktop by opening Forms Developer.
5. In the Navigator, find the Custom Library, select + to expand the Program Units node.
6. Copy Custom library to Customxx, where xx is your team number.
7. Double-click the icon for CUSTOM (Package Body) to open the package body in a
PL/SQL editor.
8. Identify the procedure event that you want to use by searching for the event.
9. Find the text Real code starts here

y
l
n

10. Enter your validation code between the proper begin and end event clauses. Your
code should execute conditionally for the Application_ID (800 for HR), Form, Block,
Event, and specific values (including your unique team suffix) requiring validation. Use
the code samples in the library or the solution below.

s
U

11. Update the date in fdrcsid, found near the end of the library file.

I
A

O
e

12. Generate CUSTOMxx.pll to create CUSTOMxx.plx by selecting the Menu option File >
Administration > Generate

&
l
a

13. Instructor: Generate your library and attach student customxx libraries. Move the new
library to the application server, under $AU_TOP/resource.

n
r
te

14. Test your code by entering an employee with last name in all uppercase and your unique
suffix.

n
I
e

l
c
a

Practice Solution: code sample

r
O

-- Practice - Custom Library Validation mm/dd/yyyy


if application_id = 800

-- HR-users

and block_name = 'PERSON'


Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 4

and event_name in ('PRE-INSERT','PRE-UPDATE') then


if name_in('person.d_suffix') = 'xx' -- your team number
if name_in('person.d_last_name') =
upper(name_in('person.d_last_name')) then
fnd_message.set_string('Please Verify Entry of Last Name');
l_button_selected:=fnd_message.question(button1 =>'Cancel',
button2

=> 'Accept',

default_btn

=> 2,

cancel_btn

=> 1);

if l_button_selected = 1 then
raise Form_trigger_failure;
end if;
end if; -- name uppercase
end if; -- your team
end if;
application
end if;

y
l
n

-- Person block and WHEN-NEW-FORM-INSTANCE and HR

-- application_id = 800

O
e

HR-users

Practice Solution: additional notes

I
A

s
U

1. Forms will use a .plx if it is available, regardless of a newer .pll . To ensure your new
library is executed, remove the old .plx, or regenerate a one by compiling the .pll with
the Menu option > File > Compile All.

&
l
a

2. If your library is not attached to a form, you can enter the Custom library path in the
forms60_path on your local machine, under Software > Oracle. Any additional or
supporting libraries should also be in your Forms home.

n
r
te

3. To use a different Form area, set APPLWRK profile (FND.Override Directory) through
Examine.

n
I
e

4. Generate from the line command uses the following syntax:


f60genm
module=xxxxx module_type=library output_file=xxxxx userid= xxx/xxx { script=yes }

l
c
a

r
O

5. Generate options include:


use the script = yes option to create a .pld (text file)
use the parse=yes option to parse .pld, producing .pll,
use the compile_all=yes option to compile .pll, producing .plx.
Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 5

Reference Only: Custom Library Examples


Entire Package and Package Body
.attach LIBRARY FNDSQF END NOCONFIRM
PACKAGE custom IS
function zoom_available
return BOOLEAN;
function style(event_name varchar2) return integer;
procedure event(event_name varchar2);
before constant integer := 1;
after constant integer := 2;
override constant integer := 3;
standard constant integer := 4;
END custom;

package body custom is


--- Customize this package to provide specific responses to events
-- within Oracle Applications forms.
--- Do not change the specification of the CUSTOM package in any way.
-- You may, however, add additional packages to this library.
--------------------------------------------------------------------function zoom_available return boolean is
--- This function allows you to specify if zooms exist for the current
-- context. If zooms are available for this block, then return TRUE;
-- else return FALSE.
--- This routine is called on a per-block basis within every Applications
-- form from the WHEN-NEW-BLOCK-INSTANCE trigger. Therefore, any code
-- that will enable Zoom must test the current form and block from
-- which the call is being made.
--

O
e

y
l
n

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 6

-- By default this routine must return FALSE.


-/* Sample code:
form_name varchar2(30) := name_in('system.current_form');
block_name varchar2(30) := name_in('system.cursor_block');
begin
if (form_name = 'DEMXXEOR' and block_name = 'ORDERS') then
return TRUE;
else
return FALSE;
end if;
end zoom_available;
*/
--- Real code starts here
-begin
return FALSE;
end zoom_available;
-------------------------------------------------------------------function style(event_name varchar2) return integer is
--- This function allows you to determine the execution style for some
-- product-specific events. You can choose to have your code execute
-- before, after, or in place of the code provided in Oracle
-- Applications. See the Applications Technical Reference manuals for a
-- list of events that are available through this interface.
--- Any event that returns a style other than custom.standard must have
-- corresponding code in custom.event which will be executed at the
-- time specified.
--- The following package variables should be used as return values:
--- custom.before
-- custom.after

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 7

O
e

y
l
n

-- custom.override
-- custom.standard
--- By default this routine must return custom.standard
--- Oracle Corporation reserves the right to change the events
-- available through this interface at any time.
-/* Sample code:
begin
if event_name = 'OE_LINES_PRICING' then
return custom.override;
else
return custom.standard;
end if;
end style;
*/
--- Real code starts here
-begin
return custom.standard;
end style;

I
A

--------------------------------------------------------------------

y
l
n

s
U

procedure event(event_name varchar2) is


--- This procedure allows you to execute your code at specific events
-- including:
--- ZOOM
-- WHEN-NEW-FORM-INSTANCE
-- WHEN-NEW-BLOCK-INSTANCE
-- WHEN-NEW-RECORD-INSTANCE
-- WHEN-NEW-ITEM-INSTANCE
-- WHEN-VALIDATE-RECORD
--

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 8

O
e

-- Additionally, product-specific events will be passed via this


-- interface (see the Applications Technical Reference manuals for
-- a list of events that are available).
--- By default this routine must perform 'null;'.
--- Oracle Corporation reserves the right to change the events
-- available through this interface at any time.
-/* Sample code:
form_name
varchar2(30) := name_in('system.current_form');
block_name varchar2(30) := name_in('system.cursor_block');
param_to_pass1 varchar2(255);
param_to_pass2 varchar2(255);
begin
-- Zoom event opens a new session of a form and
-- passes parameter values to the new session. The parameters
-- already exist in the form being opened.
if (event_name = 'ZOOM') then
if (form_name = 'DEMXXEOR' and block_name = 'ORDERS') then
param_to_pass1 := name_in('ORDERS.order_id');
param_to_pass2 := name_in('ORDERS.customer_name');
fnd_function.execute(FUNCTION_NAME=>'DEM_DEMXXEOR',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y',
OTHER_PARAMS=>'ORDER_ID="'||param_to_pass1||
'" CUSTOMER_NAME="'||param_to_pass2||'"');
-- all the extra single and double quotes account for
-- any spaces that might be in the passed values
end if;

I
A

&
l
a

s
U

n
r
te

n
I
e

-- This is an example of a product-specific event. Note that as


-- of Prod 15, this event doesn't exist.
elsif (event_name = 'OE_LINES_PRICING') then
get_custom_pricing('ORDERS.item_id', 'ORDERS.price');

l
c
a

r
O

-- This is an example of enforcing a company-specific business


Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 9

O
e

y
l
n

-- rule, in this case, that all vendor names must be uppercase.


elsif (event_name = 'WHEN-VALIDATE-RECORD') then
if (form_name = 'APXVENDR') then
if (block_name = 'VENDOR') then
copy(upper(name_in('VENDOR.NAME')), 'VENDOR.NAME');
end if;
end if;
else
null;
end if;
end event;
*/
--- Real code starts here
-form_name
varchar2(30) := name_in('system.current_form');
block_name
varchar2(30) := name_in('system.cursor_block');
l_button_selected number;
l_check
number;

O
e

begin
if form_name = 'PERWSHRG' then

I
A

s
U

if block_name = 'PERSON'
and event_name = 'WHEN-NEW-BLOCK-INSTANCE' then
--- Example #1 - Highlight Fields
-fnd_message.set_string('Would you like to highlight all required fields ?');
l_button_selected:=fnd_message.question(button1
=> 'Cancel',
button2
=> 'No',
button3
=> 'Yes',
default_btn => 2,
cancel_btn => 1,
icon
=> 'question');

&
l
a

n
r
te

n
I
e

l
c
a

r
O

y
l
n

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 10

if l_button_selected = 3 then
set_item_property('person.last_name',
VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.sex',VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.date_of_birth',
VISUAL_ATTRIBUTE,'SELECTED_DATA');
end if;
--- Example #2 - Remove Field(s)
fnd_message.set_string('Would you like to remove the Mail To field ?');
l_button_selected:=fnd_message.question(button1
=> 'Cancel',
button2
=> 'No',
button3
=> 'Yes',
default_btn => 2,
cancel_btn => 1,
icon
=> 'question');

y
l
n

O
e

I
A

s
U

if l_button_selected = 3 then
set_item_property('person.d_home_office',DISPLAYED,PROPERTY_FALSE);

&
l
a

end if;
end if; -- Person block and WHEN-NEW-FORM-INSTANCE
--- Example #3 - Override LOV

n
r
te

n
I
e

if block_name = 'PERSON' and event_name = 'WHEN-NEW-FORM-INSTANCE' then

l
c
a

l_check:=populate_group_with_query('MARITAL_LOV',
' select hl.meaning||'||''' -- ADDED TEXT '''
||' ,hl.lookup_code from hr_lookups hl '
||' where hl.lookup_type = '||'''MAR_STATUS'''

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 11

||' and hl.enabled_flag = '


||'''Y'''||' and :ctl_globals.session_date between '
||' nvl(hl.start_date_active,:ctl_globals.session_date) and '
||' nvl(hl.end_date_active,:ctl_globals.session_date) order by hl.meaning');
end if;
end if; -- Form Name = PERWSHRG
if form_name = 'PAYWSMEE' then
if block_name = 'ENTRY' and event_name in ('PRE-INSERT','PRE-UPDATE') then
--- Example #6 - Defaulting Field Values.
-- An employees market potential salary is 1.5 times their annual salary.
if name_in('entry.element_name') = 'Market Potential' then
copy(replace(to_char(round(nvl(to_number(name_in('entry.user_entry1'))*1.5,1),2),'999999990.
99'),'',''),'entry.user_entry2');
copy(name_in('entry.user_entry2'),'entry.screen_entry_value2');
end if;
end if;

y
l
n

O
e

-- Entry block

end if; -- Form Name = PAYWSMEE


end event;

I
A

s
U

BEGIN
--- You should consider updating the version information listed below as you
-- make any customizations to this library. This information will be
-- displayed in the 'About Oracle Applications' window in the Forms PL/SQL
-- section. Only change the revision, date and time sections of this string.

&
l
a

n
r
te

n
I
e

fdrcsid('$Header: CUSTOM.pld 115.5 2000/02/04 12:48:27 pkm ship


end custom;

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 12

$');

Instructor Demo and Practice: User Hook Validation


Extending Validation with Hooked Code
The objective of this demonstration and practice is to allow you to extend validation at API User
Hook points.
Given a scenario that you need to limit data entry of employee records in a certain organization
to specific titles (or other limit, as defined by your instructor), create a procedure to be accessed
by an API user hook.
For classroom purposes, test your rule by entering an employee with a unique suffix that
identifies your team number.
If you choose to create a solution for an alternate business rule, first verify with your instructor.
Instructor Note:
This practice is dependent upon successful completion of the Create Employee API user script.
Before beginning this practice, provide solution to the API practice: provide a procedure and
script to be duplicated.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 13

Instructor Demo and Practice Solution: User Hook Validation


Extending Validation with Hooked Code
Overview of steps to create and hook custom code:
1. Create additional validation as a package, limiting the code to verify against a person
whose suffix matches your PC team number.
2. Identify the required Hook_ID.
3. Hook the new procedure to the After Process hook point on the Create Employee
(published) API.
4. Test your code using the API user script you created in an earlier practice: delete the
person you entered earlier, or change field values.
Instructor Demonstration and Practice
Part 1: Create a New PL/SQL Package
A new package procedure, tutor_hook.validate_prefix validates the prefix for an employee,
allowing only the values: Dr, Sir, and Dame. Create the package, using your team number to
identify the procedure uniquely and affect only your employee entry: replace 99 with your
unique team number, the values used in your API user script.

y
l
n

O
e

s
U

create or replace package tutor_hook_99 as


procedure validate_prefix_99
(p_last_name in varchar2,
p_pre_name_adjunct in varchar2);
end tutor_hook_99;
/
create or replace package body tutor_hook_99 as
procedure validate_prefix_99
(p_last_name in varchar2,
p_pre_name_adjunct in varchar2)
is
begin
if p_last_name = 'HRTechxx' then replace xx
if p_pre_name_adjunct is not null and
p_pre_name_adjunct not in ('Dr','Sir','Dame'))
then
dbms_standard.raise_application_error(num => -20999,

I
A

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 14

msg => 'Invalid value for prefix.


Sir, and Dame');
end if;
end if;

Valid vaues are Dr,

end validate_prefix_99;
end tutor_hook_99;
/
Part 2: Register the Hook and Generate the Package Body
Register the new API user hook and generate the package body: Locate the API_HOOK_ID
for the HR_EMPLOYEE_BK1 package and CREATE_EMPLOYEE_A procedure, in the
HR_API_HOOKS table. For example, the following SQL provides the hook ID. Run the
same SQL in your instance to obtain the hook_id for your practice.
SQL>
1 select api_hook_id, api_module_id,
hook_package,
hook_procedure
2 from hr_api_hooks
3 where hook_package = 'HR_EMPLOYEE_BK1'
4* and hook_procedure = 'CREATE_EMPLOYEE_A';

y
l
n

API_HOOK_ID API_MODULE_ID
----------- ----------61
28

O
e

s
U

Register your hooked code, using the API user hook package body generation process
(hrahkall.sql).
declare
l_api_hook_call_id number;
l_object_version_number number;

&
l
a

I
A

n
r
te

begin
hr_api_hook_call_api.create_api_hook_call
(p_validate => false,
p_effective_date => to_date('01-JAN-1999','DD-MON-YYYY'),
p_api_hook_id => 61,
p_api_hook_call_type => 'PP',
p_sequence => 3000,
p_enabled_flag => 'Y',
p_call_package => 'tutor_hook_99',

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 15

p_call_procedure => 'validate_prefix_99',


p_api_hook_call_id => l_api_hook_call_id,
p_object_version_number => l_object_version_number );
end;
Confirm registry of your hooked code, using the following SQL:
SQL> select api_hook_id ID, api_hook_call_type TYPE,
call_package ,call_procedure
from hr_api_hook_calls;
ID TYPE CALL_PACKAGE
CALL_PROCEDURE
-- ---- ------------------------------61 PP tutor_hook_99
validate_prefix_99
61 PP TUTOR_12_HOOK
VALIDATE_12_PREFIX
61 PP TUTOR_08_HOOK
VALIDATE_08_PREFIX
Part 3: Call your API user Script
Call your user API script, which now will invoke the hooked code. Entering an invalid
prefix returns the following error:
SQL> start a:\hrtech\uhook99.sql
declare
*
ERROR at line 1:
ORA-20999: Invalid value for prefix.
Sir and Dame
ORA-06512: at "APPS.HR_EMPLOYEE_API",
ORA-06512: at "APPS.HR_EMPLOYEE_API",
ORA-06512: at "APPS.TUTOR_UPLOAD_99",
ORA-06512: at line 13

y
l
n

s
U

line 692
line 1086
line 28

I
A

&
l
a

Reference Information: Excerpt from hrahkpar_api


This package identifies modules accessible from user hook.
APIs (MODULE NAME) Available for User Hook Access
Module Name: ACTIVATE_EMP_ASG
Module Name: ACTUAL_TERMINATION_EMP
Module Name: ACTUAL_TERMINATION_EMP_ASG
Module Name: APPLY_FOR_INTERNAL_VACANCY
Module Name: APPROVE_SALARY_PROPOSAL
Module Name: COPY_COMPETENCIES

n
r
te

n
I
e

l
c
a

r
O

Reference Information: hrahkpar.sql


Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 16

O
e

Valid values are Dr,

This package identifies parameters at each API User hook. Caution: This file spools to
hundreds of pages. The following is an example of parameters.
SQL> start hrahkpar.sql
DOC>
Copyright (c) 1997 Oracle Corporation
DOC>
All rights reserved.
DOC>*=========================*/
Parameters Available at each API User Hook
==========================================
Created on 2001/09/16 16:19:11 (YYYY/MM/DD HH:MM:SS)
Module Name: ACTIVATE_EMP_ASG
Module Type: Business Process API
Hook: After Process
P_EFFECTIVE_DATE
P_DATETRACK_UPDATE_MODE
P_ASSIGNMENT_ID
P_CHANGE_REASON
P_OBJECT_VERSION_NUMBER
P_ASSIGNMENT_STATUS_TYPE_ID
P_EFFECTIVE_START_DATE
P_EFFECTIVE_END_DATE

DATE
VARCHAR2
NUMBER
VARCHAR2
NUMBER
NUMBER
DATE
DATE

Hook: Before Process


P_EFFECTIVE_DATE
P_DATETRACK_UPDATE_MODE
P_ASSIGNMENT_ID
P_CHANGE_REASON
P_OBJECT_VERSION_NUMBER
P_ASSIGNMENT_STATUS_TYPE_ID

DATE
VARCHAR2
NUMBER
VARCHAR2
NUMBER
NUMBER

&
l
a

I
A

y
l
n

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 17

O
e

Instructor Demo and Practice: Database Item Components


Instructor Demonstration and Practice
The objective of this demonstration and practice is to allow you to investigate Database Item
components in consideration of designing and creating database items.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 18

Solution: Database Item Components


Examining Database Items: QuickPaint Report
Note: Quickpaint reports can use assignment_id and date_earned as contexts.
Create a QuickPaint report to list an employee name, hire_date, address, work information
including organization and address.
1. Define the report using database items. Navigate to the QuickPaint window using your
Super HRMS Manager
(N) Processes and Reports > Define a QuickPaint Report
2. Enter the following labels and fields for your report:
Report Name: xxEmployee Address Report, where xx is your unique team number.
Definition:
Hire Date: &EMP_HIRE_DATE
Employee Number: &PER_EMP_NUMBER
Employee Name: &PER_FULL_NAME
Residence:
Address Line 1: &PER_ADR_LINE_1
Address Line 2: &PER_ADR_LINE_2
Address Line 3: &PER_ADR_LINE_3
City, State, Zip: &PER_ADR_CITY, &PER_ADR_US_STATE_CODE
&PER_ADR_POSTAL_CODE

y
l
n

O
e

Work Location:

I
A

&ASG_ORG

&
l
a

s
U

Address Line 1: &LOC_ADR_LINE_1


Address Line 2: &LOC_ADR_LINE_2
Address Line 3: &LOC_ADR_LINE_3
City, State, Zip: &LOC_ADR_CITY, &LOC_ADR_US_STATE_CODE
&LOC_ADR_POSTAL_CODE

n
r
te

n
I
e

l
c
a

3. Save your report, create an assignment set with a single employee, then run the report for
your assignment set:

r
O

(N) Processes and Reports -> Run a QuickPaint Report in the Navigator

4. View the results, similar to the following:


xxEmployee Address Report
Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 19

Hire Date: 01-JAN-2001


Employee Number: 25
Employee Name: Hourly, Nancy
Residence:
Address Line 1: 1515 Gough Street
Address Line 2:
Address Line 3:
City, State, Zip: San Francisco, CA 94109
Work Location:

Oracle Corp.

Address Line 1: 500 Oracle Parkway


Address Line 2:
Address Line 3:
City, State, Zip: Redwood City, CA 94065
5. You can apply the following to database items that you design and create, validating
contexts and parameters. To follow resolution of a database item, consider
PER_ADR_LINE_1 in our example. The following SQL represents the high level database
item definition:

y
l
n

O
e

s
U

SELECT USER_NAME, DEFINITION_TEXT, USER_ENTITY_ID


FROM FF_DATABASE_ITEMS
WHERE USER_NAME = PER_ADR_LINE_1;
USER_NAME
-------------PER_ADR_LINE_1

I
A

DEFINITION_TEXT
USER_ENTITY_ID
----------------------ADDR.address_line1
3

&
l
a

n
r
te

Replacing this information into the Select statement, we have:


SELECT ADDR.address_line1
SELECT ROUTE_ID FROM FF_USER_ENTITIES
WHERE USER_ENTITY_ID = 3;

n
I
e

l
c
a

r
O

ROUTE_ID
--------------3

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 20

SELECT TEXT
FROM FF_ROUTES
WHERE ROUTE_ID = 3;

TEXT
---------------------------------------------------/* Person address details */
per_all_assignments_f ASSIGN
,
per_addresses
ADDR
,
fnd_territories_vl
a
where
to_date (&B1, 'DD-MON-YYYY') BETWEEN
ASSIGN.effective_start_date
AND
ASSIGN.effective_end_date
and
ASSIGN.assignment_id
= &B2
and
ADDR.person_id
(+)= ASSIGN.person_id
and
ADDR.primary_flag
(+)= 'Y'
and
to_date (&B1, 'DD-MON-YYYY')
BETWEEN nvl(ADDR.date_from,
to_date (&B1, 'DD-MON-YYYY'))
TEXT
---------------------------------------------------AND nvl(ADDR.date_to,
to_date (&B1, 'DD-MON-YYYY'))
and
a.territory_code
(+)= ADDR.country

y
l
n

O
e

We determine the FROM and WHERE clauses to be:

&
l
a

I
A

s
U

FROM per_all_assignments_f ASSIGN,


per_addresses
ADDR,
fnd_territories_vl
a

n
r
te

n
I
e

WHERE to_date (&B1, 'DD-MON-YYYY') BETWEEN


ASSIGN.effective_start_date
AND ASSIGN.effective_end_date
and
ASSIGN.assignment_id
= &B2
and
ADDR.person_id
(+)= ASSIGN.person_id
and
ADDR.primary_flag
(+)= 'Y'
and
to_date (&B1, 'DD-MON-YYYY')
BETWEEN nvl(ADDR.date_from,

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 21

AND
and

to_date (&B1, 'DD-MON-YYYY'))


nvl(ADDR.date_to,
to_date (&B1, 'DD-MON-YYYY'))
a.territory_code
(+)= ADDR.country

At this level we see &B1 and &B2, which are placeholders referencing contexts in the tables
FF_ROUTE_CONTEXT_USAGES and FF_CONTEXTS.
Note: Placeholders are variables in the WHERE clause that make the SQL more dynamic. The
two types of placeholders are &U# and &B#, where # refers to a sequence number.
&B# placeholders reference contexts in the tables FF_ROUTE_CONTEXT_USAGES and
FF_CONTEXTS. Context values are passed to the formula at runtime; they are not fixed
values.
&U# placeholders are based on the user entity: they reference parameters and parameter
values in the tables FF_ROUTE_PARAMETERS and
FF_ROUTE_PARAMETER_VALUES. The available values for &U# place holder are
fixed; they are not passed through the formula.
In our example, we can resolve the placeholders further, with the following:
SQL> select SEQUENCE_NO, CONTEXT_ID
2 from ff_route_context_usages
3 where route_id = 3;
SEQUENCE_NO
----------1
2

O
e

CONTEXT_ID
---------8
6

I
A

s
U

Notice sequence 1, 2 correspond to &B1, &B2:


context_id 8 refers to &B1, and context_id 6 refers to &B2.

&
l
a

n
r
te

We can further resolve the contexts, with the following:


SQL> select context_id, context_name
2 from ff_contexts
3 where context_id in (8,6);

l
c
a

n
I
e

r
O

CONTEXT_ID
--------6
8

y
l
n

CONTEXT_NAME
-----------------------------ASSIGNMENT_ID
DATE_EARNED
Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 22

We now see that the value of &B1 is Date_earned,


and the value of &B2 is assignment_id.
To run this query in SQL*Plus, the values for assignment_id and date_earned would be replaced
as follows:
SELECT ADDR.address_line1
FROM per_all_assignments_f ASSIGN,
per_addresses
ADDR,
fnd_territories_vl
a
WHERE to_date ('24-JUL-1999', 'DD-MON-YYYY') BETWEEN
ASSIGN.effective_start_date
AND
ASSIGN.effective_end_date
and
ASSIGN.assignment_id
= 122
and
ADDR.person_id
(+)= ASSIGN.person_id
and
ADDR.primary_flag
(+)= 'Y'
and
to_date ('24-JUL-1999','DD-MON-YYYY')
BETWEEN nvl(ADDR.date_from, to_date ('24-JUL-1999', 'DD-MONYYYY'))
AND
nvl(ADDR.date_to,
to_date ('24-JUL1999', 'DD-MON-YYYY'))
and a.territory_code (+)= ADDR.country

y
l
n

O
e

Which resolves &PER_ADR_LINE_1, returning:

I
A

s
U

ADDRESS_LINE1
--------------------------------------------------1515 Marvin Street

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 23

Instructor Demonstration: Creating a Function


The objective of this demonstration and practice is to allow you to examine components and
strategy used to create a user-defined function that can be called from FastFormula.
Given a scenario that you need a custom function to provide validation, you can design a
function that uses parameters and contexts. The calling Formula can also access database items,
further extending the logic without complex code.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 24

Instructor Demonstration and Practice Solution


Creating a Function
Given a business rule that requires validation on a segment of the Additional Assignment
Descriptive Flexfield, which has the format of a national identifier. For discussion of contexts,
assume the function is called from Oracle Payroll. This example is for demonstration purposes
only: assume the specific validation cannot be accommodated in flexfield validation
configuration.
Design Considerations
1. Determine what can be addressed in the formula and the specific requirements for a
function. Validation should confirm national identifier format, as associated with the
business group legislation. You can provide the national identifier format mask(s) in
global value(s) or hard-code the format(s) into the PL/SQL function.
2. Consider the input values and data sources. Recall that you can run a concurrent process
to create database items for Flexfields. The formula type determines which contexts are
available. Identify any parameters required, for example, to pass formula values to the
function. Data available to you include:
parameters
contexts
global values (available in the Formula and easy to maintain)
- balances and database items (available in the Formula)
external data available through PL/SQL.

y
l
n

O
e

s
U

3. Review your design, then create the PL/SQL function. For purposes of this practice,
model your solution on the existing PL/SQL function,
hr_ni_chk_pkg.chk_nat_id_format.

I
A

4. Register your function in the Forms; identify required contexts and parameters.

&
l
a

5. Create or modify a payroll formula to call the function, and complete testing.

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 25

Registering the Function


1. Navigate to the Define Functions window using your Super HRMS Manager
responsibility.
(N) Other Definitions > Formula Functions
2.

Enter the function definition using these values, where xx is your team number:
Name
Data Type
Alias
Description
Definition

3.

Xx_validate
Text
Xx_validate
(optional)
hr_ni_chk_pkg.chk_nat_id_format

Save your work., and close the Formula Functions window.

4. Enter context usages, if required. Navigate to the Context Usages window by choosing
the Context Usages button.
Sequence Number
1
2

5.

Context Name
Business_Group_ID
Assignment_ID

Data Type
Number
Number

y
l
n

Save your work, and exit the Context Usages window.

6. Enter parameters, if you determine that they are required. Navigate to the Parameters
window by choosing the Parameters button. (Hint: you can look at the reference function
provided below.)
Number
1
2

7.

Parameter Name
National_Identifier
Format

Type
Text
Text

Class
Input Only
Input Only

I
A

O
e

s
U

Save your changes and exit, closing the Parameters and Define Functions
windows.Reference Information CHK_NAT_ID_FORMAT function

&
l
a

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 26

Reference Information
Notes: These excerpts from the package header and body are simply for reference of
parameters in the PL/SQL code.
Package body file and object name:
hr_ni_chk_pkg AS

PACKAGE BODY

/* $Header: penichk.pkb 115.18 2001/03/19 03:24:47 pkm ship

$ */

Note the Comments.


You are not required to access or change code for this practice.
PACKAGE hr_ni_chk_pkg AUTHID CURRENT_USER AS
/* $Header: penichk.pkh 115.4 2000/05/04 04:18:07
Name
: hr_ni_chk_pkg (HEADER)
*/
--------- validate_national_identifier ---- Pass in national identifier and validate both
-- construct (dependent on the legislation of the
-- business group) and uniqueness within business
-- group
-FUNCTION chk_nat_id_format
( p_national_identifier VARCHAR2,
p_format_string
VARCHAR2) RETURN VARCHAR2;
end hr_ni_chk_pkg;

O
e

y
l
n

s
U

FUNCTION chk_nat_id_format(
/* This function checks that a supplied national identifier is
in the specified format. It also ensures that the correct
format mask is applied to the national identifier, which is
then returned to the calling program. If the validation fails
then the rountine passes back a '0'.
It should conform to business process validation standards,
from which it is called in order that the person API routines
remain under the control of one person. */
p_national_identifier
IN VARCHAR2,
p_format_string
IN VARCHAR2
) RETURN VARCHAR2 AS

I
A

&
l
a

n
r
te

l
c
a

n
I
e

l_nat_id
l_format_mask
l_format_string
l_valid

r
O

VARCHAR2(30);
VARCHAR2(30);
VARCHAR2(30);
NUMBER;

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 27

Procedure / Functions and Parameters


PROCEDURE CHECK_NI_UNIQUE
Argument Name
Type
In/Out Default?
---------------- --------- ------ -------P_NATIONAL_IDENTIFIER VARCHAR2
IN
P_PERSON_ID
NUMBER
IN
P_BUSINESS_GROUP_ID
NUMBER
IN
P_RAISE_ERROR_OR_WARNING VARCHAR2 IN
FUNCTION CHK_NAT_ID_FORMAT RETURNS VARCHAR2
Argument Name
Type
In/Out Default?
----------------- ---------- ------ -------P_NATIONAL_IDENTIFIER VARCHAR2
IN
P_FORMAT_STRING
VARCHAR2
IN
FUNCTION VALIDATE_NATIONAL_IDENTIFIER RETURNS VARCHAR2
Argument Name
Type
In/Out Default?
---------------- ------------- ------ -------P_NATIONAL_IDENTIFIER
VARCHAR2
IN
P_BIRTH_DATE
DATE
IN
P_GENDER
VARCHAR2
IN
P_BUSINESS_GROUP_ID
NUMBER
IN
P_SESSION_DATE
DATE
IN

O
e

y
l
n

FUNCTION VALIDATE_NATIONAL_IDENTIFIER RETURNS VARCHAR2


Argument Name
Type
In/Out Default?
-------------------- --------- ------ -------P_NATIONAL_IDENTIFIER VARCHAR2 IN
P_BIRTH_DATE
DATE
IN
P_GENDER
VARCHAR2
IN
P_EVENT
VARCHAR2
IN
DEFAULT
P_PERSON_ID
NUMBER
IN
P_BUSINESS_GROUP_ID NUMBER
IN
P_LEGISLATION_CODE
VARCHAR2
IN
P_SESSION_DATE
DATE
IN
P_WARNING
VARCHAR2
OUT
P_PERSON_TYPE_ID
NUMBER
IN
DEFAULT

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 28

Instructor Demonstration and Practice: Configuring a Template


The objective of this demonstration and practice is to allow you to observe Forms Configurator
capabilities.
Given a scenario that you need a custom form with user-specific field labels, default values for
certain fields, certain fields hidden from the user, and mouse-over help.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 29

Solution: Configuring a Template


Using Forms Configurator with a People Management Template
Business requirements demand a version of the Enter Employee window for temporary data
entry personnel. You must configure the form for ease of data entry, including: hide nonrequired fields, default the person type, and provide mouse-over help
Access and copy the delivered template
1. Navigate to the Find Templates window using your Super HRMS Manager
(N) Security > People Management Configurator
2. In the Find window, enter PER_ENTER_EMPS from the list of values in the Template
Code field. This displays the existing templates, from which you can copy and configure
a new form.
3. Press OK to select the template name matching your legislation, if available.
4. Click on Copy. This results in a copy of the delivered template. You can now modify
your copy to configure a new template reflecting your business needs.

y
l
n

5. In the Copy Template window, enter a new code and name for your form. Use a name
such as XX EMPS in the template code field and XX Employees in the template name
field, where XX is your unique team number.

O
e

6. Select Yes in the enabled field.


7. Optionally, enter a legislation.
8. Press OK, and Save when prompted with a choice.

I
A

s
U

9. Enter XX EMPS in the template code field, where XX is your unique team number.

&
l
a

10. Enter XX Employees in the template name field. This is the name that will be displayed
to end users.

n
r
te

11. Confirm the Enabled field is Yes.

n
I
e

12. Click on OK.

l
c
a

13. Save your work.

r
O

Configure your new template


14. In the Template Code field, enter XX EMPS.

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 30

15. Click on Edit. You will now have your template visible as a form and with a designer
interface. This is where you modify the Form: you can move fields, add defaults, and so
forth. Save your work when prompted.
16. Click on the + of XX Employees Folder.
17. Click on the + of the Items in your XX Employees Folder. This will provide you with a
list of all the values in this form.
18. Note: the Context attribute is presently used only for Position copy. This feature controls
access of fields dependent on the Application, Legislation, and Responsibility.
19. Click on an item, such as the Person Type Item.
20. With the Person Type highlighted, move the scroll bar along the field attributes. Note
the Person type field position on the form window.
21. Move the Person Type field, changing the x coordinate to 5. You will see the field move
to the left. (Field position changes are faster using the x and y coordinates rather than the
arrows.)
22. Scroll to the Default Value field. Enter the Value of Employee. You can add default
values for other fields. Move from the Default field and observe the label in the working
form window.

y
l
n

23. Change the field label by scrolling to the Prompt Text field. Enter a new value for the
displayed field label.

O
e

24. Scroll to the Tool Tip field for the Person Type field. Add the text: System Person Type.
When you tab out of the field, move the mouse cursor over the field, observing your new
help text. (Note the course and online help cautions about overriding help text.)

I
A

s
U

25. You can hide fields. Select the Person Type field. Scroll to the Visible attribute,
changing it from Yes to No. The field is now hidden from the user, but records entered
have the default value.

&
l
a

26. Examine other options, including Formula. (Recall that Configurator Formula
definitions are limited to 5 input values.)

n
r
te

27. After configuration has been completed, you can add the form to your menu structure, or

n
I
e

into a taskflow.

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 31

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Business Rule Extensions Demos and Practices


Chapter 15 - Page 32

Extending Security: Demo


and Practice
Chapter 16

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 1

Extending Security Demo and Practice


Job Title*
The Job Title [list@YourCompany.com?Subject=EDUxxxxx] is responsible for ensuring that
this document is necessary and that it reflects actual practice.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 2

Instructor Demonstration and Practice Solution


Custom Security Profile
This demonstration and practice builds a security structure using the Custom option, which
permits you to define a SQL where clause fragment that extends the security profile.
Using the business requirement of segregating access to employee and applicant data by
organization and location (and/or further detail), define a security profile for data access.
Associate the profile with a new responsibility, then switch to that responsibility to observe the
data restriction.
Overview of practice steps:
1. Plan your security profile including the business group, organization(s), position(s) and
payroll(s).
2. Create a new security profile; create a unique responsibility for testing, add it to your user.
3. Run Security List Maintenance (LISTGEN) as a concurrent process, to update the security
profile list with your new security profile.
4. Set the HR:Security Profile to your new security profile for your responsibility.
5. Query employee data using your test responsibility before adding a custom restriction;
identify data that will validate your restriction.
6. Modify your security profile, adding your Custom restriction. The fragment can relate to
location, job, person name, or another entity.
7. Again run LISTGEN to capture updates.
8. Test your security profile changes.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 3

Instructor Demonstration and Practice Solution


1. Plan a Security Profile
Scenario: Your instructor will direct you to limit security based on specific data, which may
include some of the following, depending on your legislation.

Location_ID

Location

Legislation

202

HR- San Francisco

US

206

D2- Miami

US

451

HR- Atlanta

US

307

HR- Bristol, UK

UK

432

HR- Newcastle, UK

UK

454

HR- Reading, UK

UK

Security Profile Design


Component

Name

Notes

Security Profile

HRTechxx /

Business Group

I
A

&
l
a

Organization(s)

Job, Name or other


entity*

s
U

n
I
e

l
c
a

r
O

O
e

n
r
te

Payroll(s)
Location(s)*

y
l
n

*These entities will be added separately, using the Security Profile Custom tab.

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 4

Instructor Demonstration: Custom Security Profile


2. Define a Security Profile
1. Using your Super HRMS Manager Responsibility, Navigate to the Security Profile window:
(N) Security > Profile > Define
Define a Security Profile, using the following information:
Enter your security profile name, such as XX_HRTech.
View all records, employees, applicants: blank or unchecked.
Select an Organization Hierarchy, such as Reporting Hierarchy (US)
Check Include Top Organization
Identify the Top Organization for this profile, from your planning table.
Select View All Positions and use defaulted Position fields.
Select View All Payrolls and use defaulted Payroll fields.
Save your work and close the window.
2. Define a Responsibility for testing your Security Profile. Using your System Administrator
Responsibility, Navigate to the Responsibility window:
(N) Security > Responsibility > Define
1. Query in your local (Super) HRMS Manager responsibility, noting the following:
Data Group _______________________
Menu
_______________________
Request Group ____________________
2. Define a new Responsibility,
Enter a unique name, such as XX_HRTech
Complete the rest of the form using the information identified above.
Enter a unique name for the Responsibility Key (it is used internally).
Save your work and close the window.
3. Add your Responsibility to your user. Using your System Administrator Responsibility,
Navigate to the User window:
(N) Security > User > Define
Query in your Application logon username, such as HRMSxx.
In the lower region, enter your new responsibility:
Click the green + on the toolbar to add a record.
Select your Responsibility, such as XX_HRTech, using the LOV.
Save your work and close the window.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 5

Instructor Demonstration and Practice Solution


3. Run Security List Maintenance
Run Security List Maintenance (LISTGEN) as a concurrent process, to update the security
profile list with your new security profile.
1. Navigate to the Submit Processes and Reports window using your (Super) HRMS Manager
Responsibility:
(N) Processes and Reports > Submit Process and Report > Single Request
2. In the Request Name field, select Security List Maintenance from the list of values.
3. In the Parameters window: enter the date as today; select your XX_HRTech Security Profile
from the list of values. (You created this in Step 2, part 1.)
4. Select the Submit Request button. Note your request ID: __________
5. View the results of the report by navigating to the Results window:
(N) Processes and Reports > View > All My Requests.

4. Identify HR:Security Profile Option

y
l
n

Set the HR:Security Profile to your new profile at the Responsibility level.

Navigate to the Security Profile window using your System Administration Responsibility:
(N) Security > Profile
1. Specify the Profile Option and the Responsibility in the Find Window.
2. Uncheck Site, Application, and User.
3. Check Responsibility; select your Responsibility name (such as XX_HRTech) from the list
of values.
4. Enter HR:Security Profile for the profile option; you can optionally use HR%Sec% (Hint:
Some profile option names use spaces before or after the : and others do not. )
5. Set the value for your Security Profile to your Responsibility.
6. Save your work and close the window.

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 6

Instructor Demonstration and Practice Solution


5. Identify test data
Use your new test Responsibility to query employee data before adding a custom restriction;
identify data that will validate your restriction.
1. From the toolbar, use the File options to use your test Responsibility
2. (T) File > Switch Responsibility.
3.

Select your XX_HRTech Responsibility.

4. Navigate to the List Employees by Organization window:


> -> Employees by Organization

(N) View > Lists

5. Note specific employees. You can list employee names or other values here:
6. Obtain the values to limit your Security Profile. You can use the Toolbar Help >
Diagnostics > Examine to find IDs for specific values, such as location or job.
Alternatively, you can use SQL*Plus to find values or IDs.
6. Modify Security Profile: Custom Restriction

y
l
n

O
e

Modify your security profile, adding your Custom restriction. The fragment can relate to
location, job, person name, or another entity.
Using your Super HRMS Manager Responsibility, Navigate to the Security Profile window:
(N) Security > Profile > Define
1. Query your Security Profile, such as XX_HRTech.
2. Select the Custom tab.
3. Check the Custom checkbox.
4. Enter the where fragment into the custom window. You do not need quotes or the word
where. For example, you can enter:
assignment.location_id = 202 and person.last_name like B%
5. Press the Verify button. Look for the message at the bottom of the window, indicating that
your code has been verified.
6. Save your work and close the window.

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 7

Instructor Demonstration and Practice Solution


7. Update Security Lists
Run Security List Maintenance to capture Security Profile updates. This concurrent process
updates security lists.
1. Navigate to the Submit Processes and Reports window using your (Super) HRMS Manager
Responsibility:
(N) Processes and Reports > Submit Process and Report > Single Request
2. In the Request Name field, select Security List Maintenance from the list of values.
3. In the Parameters window: enter the date as today; select your XX_HRTech Security Profile
from the list of values. (You created this in Step 2, part 1.)
4. Select the Submit Request button. Note your request ID: __________
5. View the results of the report by navigating to the Results window:
(N) Processes and Reports > View > All My Requests.
8. Test Custom Security Profile
Test your security profile changes. Use your test Responsibility to query employee data,
verifying your updated Custom Security Profile.
1. From the toolbar, use the File options to use your test Responsibility
(T) File > Switch Responsibility.
2. Select your XX_HRTech Responsibility.
3. Navigate to the List Employees by Organization window:
(N) View > Lists
> -> Employees by Organization
4. Note specific employees, comparing to employees identified in part 4.

y
l
n

O
e

I
A

&
l
a

s
U

n
r
te

n
I
e

l
c
a

r
O

Copyright Oracle Corporation, 2002. All rights reserved.

Extending Security Demo and Practice


Chapter 16 - Page 8