PURPOSE

------To explain how to enter data into Oracle HRMS by means of the Application
Programming Interface (API).
SCOPE & APPLICATION
------------------This document gives guidance,with the help of examples, on how to use an API, and
explains also how an API is constructed and what the various components are.
CONTENT
------1. General Introduction
2. Structure of APIs
2.1 API Layout
2.2 Defaults
2.3 Control Parameters
3. Flexfield Validation
4. Examples
4.1 Create Style API
4.2 Update Style API
4.3 PL/SQL Batch Program
5. Limitations
6. Common Problems
Fig: 1. General Introduction
----------------------The Application Programming Interface or API is a PL/SQL packaged procedure which
can be used as an alternative entry point into the system to the traditional online forms.
In R9 of Oracle Applications all the data validation and table handling logic was resident
in the form. From R10 onwards this has been moved into stored PL/SQL procedures in
the database. The advantage being that the same logic used by the seeded online forms
can also be used by other interfaces into the system, thus ensuring that the integrity of
the data remains intact. APIs are also fully supported and protect the user from any
structural changes to the schema, although it can never be guaranteed that the
program interface will not change which would require any bespoke programs using the
API to be changed too. The APIs available in Oracle HRMS have been written to fulfil
business needs. i.e. Create Employee, Update Person Address,
and can be used in many ways. For example
a) Data Uploads - Bulk transfer of data from an existing system into
Oracle HRMS.
b) Interfacing - Regular interface from,for example, a 3rd party Personnel
system into Oracle Payroll.
c) Spreadsheets - Uploading data via ADE.

d) Forms

- standard interface, standard or web forms.

HRMS APIs are designed to load information to systems that have a full
installation of Oracle Human Resources. They are not designed to load
information for other Oracle applications that use Human Resources (HR)
in a Shared mode (i.e. Payables, Purchasing, CRM). For release 10.7 and 11.0
there are no HRMS APIs that are supported for loading information to a systemusing HR
in a Shared mode. For release 11i, there are a limited number of APIsthat are
supported for loading HR Foundation information. For a list of these .
APIs, review HR Foundation and APIs.
2. Structure of APIs
-------------------2.1 API Layout
-------------APIs are held as PL/SQL packages in the database,and are delivered by SQL
scripts which are held on the server in the admin/sql directories under eachproduct, or
patch/115/sql if patched after the baseinstall of R11i.
The scripts come as separate header and body files. For a
description of the API including a list of the parameters, you can refer to theheader. i.e.
peaddapi.pkh. Alternatively you can describe the API packagein SQL*Plus. e.g. desc
hr_person_address_api.create_gb_person_address. In
Oracle 8, however, it is not possible to describe the procedure name, only the package.
Fig.1 - Example of an API
procedure create_gb_person_address
(p_validate
in
boolean default false
,p_effective_date
in
date
,p_person_id
in
number
,p_primary_flag
in
varchar2
,p_date_from
in
date
,p_date_to
in
date
default null
,p_address_type
in
varchar2 default null
,p_comments
in
long default null
,p_address_line1
in
varchar2
,p_address_line2
in
varchar2 default null
,p_address_line3
in
varchar.
2 default null
,p_town
in
varchar2 default null
,p_county
in
varchar2 default null
,p_postcode
in
varchar2 default null
,p_country
in
varchar2
,p_telephone_number
in
varchar2 default null
,p_telephone_number_2
in
varchar2 default null
,p_addr_attribute_category
in
varchar2 default null
,p_addr_attribute1
in
varchar2 default null
,p_addr_attribute2
in
varchar2 default null
,p_addr_attribute3
in
varchar2 default null
,p_addr_attribute4
in
varchar2 default null

,p_addr_attribute5
,p_addr_attribute6
,p_addr_attribute7
,p_addr_attribute8
,p_addr_attribute9
,p_addr_attribute10
,p_addr_attribute11
,p_addr_attribute12
,p_addr_attribute13
,p_addr_attribute14
,p_addr_attribute15
,p_addr_attribute16
,p_addr_attribute17
,p_addr_attribute18
,p_addr_attribute19
,p_addr_attribute20
,p_address_id
,p_object_version_number
);

in
in
in
in
in
in
in
in
in
in
in
in
in
in
in
in
out

varchar2 default null

varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
varchar2 default null
number
out number

As can be seen above in Fig. 1, each API has several parameters. Some are
control parameters which affect the processing logic (See 2.3), but most
map onto a database column and are either passed to the API as an IN parameter,or
automatically generated as an OUT parameter, often because it is a surrogatekey ID of a
base table. i.e. address_id. Out parameters must be set withvariable names to receive
values that are passed OUT.
2.2 Defaults
------------------------------------------------------------------------------------------When calling an API you only need to specify the required parameters, which
are those that do not have defaults, and those parameters that you wish to
enter information against. The default values vary depending on the API style.
Create Style APIs
----------------------------------------------------------------------------------------Optional parameters are usually defined with a default value of null.
Sometimesparameters are specified as In/Out which means they can be one or the
other.
For instance, p_employee_number in the create_employee API. If employee
numbergeneration is set to Manual a value must be passed IN, but if it is Automaticthe
value passed in must be null, and a value is subsequently passed Out.
Update Style APIs
------------------------------------------------------------------------------------------Optional parameters are defined with one of the following default parametersdepending
on the datatype:
Varchar2
Number
Date

hr_api.g_varchar2
hr_api.g_number
hr_api.g_date

If you do not want to alter the existing values on the database then the
parameter should be excluded, or pass one of the above as the default.
Delete Style APIs
------------------------------------------------------------------------------------------Most parameters do not have defaults, but when they do they work in a similarway to
update style APIs.
2.3 Control Parameters
--------------------------------------------------------------------------------------------Most Control Parameters do not map onto database columns, but affect processing
logic. The exception is the Object Version Number (OVN). This section will go
through each control parameter in turn and explain it's function.
Object Version Number
--------------------------------------------------------------------------------------------The OVN controls record locking within the HRMS application. When a new row
isinserted into the database, the OVN is usually set to 1. If it is subsequently updated, it
is inc.remented by 1. Whenever a row is read and transferred toa client, the OVN is
always transferred and this is used to determine if therecord has been changed since the
user retrieved the original data. For example,two users access the same record
simultaneously, they will both have read the
same value for the OVN. One updates the record and the OVN increments to, for
example, a value of 2. The second user then updates and will get an error message
because the value of the OVN that was originally read (1) is now different to the value
on the database (2). The following message will be displayed 'Record has been modified
by another user', and the u.ser is invited to re-query the record.
This is the reason why the OVN is so important when calling APIs. For createstyle APIs,
the parameter is defined as an OUT parameter and is always initialised. For update style
apis the parameter is In/Out and must be passedIN. If the OVN passed in does not
match what's on the database at the time of the update, an application error
'HR_7155_OBJECT_LOCKED' will be raised.
p_validate
-----------------------------------------------------------------------------------------This parameter is used to control whether the database is updated or not. Thedefault is
False, which means that the API performs normally by doing allneccesary
validation,insert,update or deletes.
If it is set to True then the API will just check that the operation will be valid. All
insert,update or delete operations are rolled back.
Note: There are no commits done from within the API. These must be done
from the calling program. see section 4.3.

p_effective_date
--------------------------------------------------------------------------------------------This is a datetrack parameter, and is the date when the particular insertionor change
becomes effective. It will only be present in those APIs which areperforming operations
on datetracked tables. It is used in conjunctionwith one of the modes below.
p_datetrack_update_mode
-----------------------------------------------------------------------------------------APIs that do updates on at least one datetracked table will contain this
parameter. It defines the type of datetracked operation to be performed. Thechoices are
UPDATE
Keep history of existing information
CORRECTION
Correct existing information
UPDATE_OVERRIDE
Replace all scheduled changes
UPDATE_CHANGE_INSERT
Insert this change before next scheduled change.
Please note that the OVN for each datetrack change for the same primary keywill be
different. It is,therefore, important that the correct datetrack recordis read for the
appropriate datetrack mode of operation. i.e; at the correct
p_effective_date.

p_datetrack_delete_mode
----------------------------------------------------------------------------------------APIs that do delete operations on a datetracked table will contain this
parameter. It allows you to define the type of datetrack deletes to make.
The choices are
ZAP
Completely remove from database
DELETE
Set end date of record to effective date
FUTURE_CHANGE
Remove all scheduled changes
DELETE_NEXT_CHANGE
Remove next change
Same point about OVN mentioned above is relevant here too.
p_effective_start_date/p_effective_end_date
--------------------------------------------------------------------------------------------These two dates are passed OUT whenever a datetrack operation is made.
They are set to NULL when a delete style uses ZAP mode.
3. Flexfield Validation
--------------------------------------------------------------------------------------APIs now include automatic Flexfield ValueSet validation.
4. Examples
Below are some examples of how to call APIs. Sections 4.1/4.2 show the Createand
Update Address APIs being called once only. Section 4.3 shows the Create Address API

called in a loop.
4.1 Create Style API
--------------------------------------------------------------------------------------------l_object_version_number
l_address_id

number;
number;

begin
hr_person_address_api.create_gb_person_address
(p_validate
=>
false
,p_effective_date
=>
trunc(sysdate)
,p_person_id
=>
1103
,p_primary_flag
=> .
'Y'
,p_date_from
=>
trunc(sysdate)
,p_address_line1
=>
'101 Gasworks Lane'
,p_country
=>
'GB'
,p_address_id
=> l_address_id
,p_object_version_number
=> l_object_version_number
);
end;
4.2 Update Style API
--------------------------------------------------------------------------------------------declare
l_object_version_number

number;

cursor csr_address is
select object_version_number
from per_addresses where address_id=323;
begin
open csr_address;
fetch csr_address into l_object_version_number;
close csr_address;
hr_person_address_api.update_gb_person_address
(p_validate
=> false
,p_effective_date
=>
to_date('17-jun-1999','dd-mon-yyyy')
,p_address_id
=> 323
,p_address_line2
=> 'Suburbia'
,p_object_version_number
=> l_object_version_number
);
end;
4.3 PL/SQL Batch Program
---------------------------------------------------------------------------------------------

declare
-l_rows_processed
number := 0; -- rows processed by api
l_commit_point
number := 20; -- Commit after X successful
rows
l_batch_run_number
number;
l_dummy_line_id
number;
l_address_id
number;
l_object_version_number number;
--- select the next batch run number
-cursor csr_batch_run_number is
select nvl(max(abm.batch_run_number), 0) + 1
from hr_api_batch_message_lines abm;
--- select all the temporary 'GB' address rows
-cursor csr_tpa is
select tpa.person_id
, tpa.primary_flag
, tpa.date_from
, tpa.address_type
, tpa.address_line1
, tpa.address_line2
, tpa.address_line3
, tpa.town
, tpa.county
, tpa.postcode
, tpa.country
, tpa.telephone_number
, tpa.rowid
from temp_person_addresses tpa;
begin
-- open and fetch the batch run number
open csr_batch_run_number;
fetch csr_batch_run_number into l_batch_run_number;
close csr_batch_run_number;
-- open and fetch each temporary address row
for sel in csr_tpa loop
begin
-- create the address in the HR Schema
hr_person_address_api.create_gb_person_address
(p_validate
=> true
,p_effective_date
=> sel.date_from
,p_person_id
=> sel.person_id
,p_primary_flag
=> sel.primary_flag
,p_date_from
=> sel.date_from
,p_address_type
=> sel.address_type

,p_address_line1
=> sel.address_line1
,p_address_line2
=> sel.address_line2
,p_address_line3
=> sel.address_line3
,p_town
=> sel.town
,p_county
=> sel.county
,p_postcode
=> sel.postcode
,p_country
=> sel.country
,p_telephone_number
=> sel.telephone_number
,p_address_id
=> l_address_id
,p_object_version_number => l_object_version_number
);
-- increment the number of rows processed by the api
l_rows_processed := l_rows_processed + 1;
-- determine if the commit point has been reached
if (mod(l_rows_processed, l_commit_point) = 0) then
-- the commit point has been reached therefore commit
commit;
end if;
exception
when others then
--- An API error has occurred
-- Note: As an error has occurred only the work in the last API
-call will implicitly rolled back. The uncommitted work
-done by previous API calls will not be affected.
-If the error is ora-20001 the fnd_mess.
age.get function
-will retrieve and substitute all tokens for the short
-and extended message text.
-If the error is not ora-20001 null will be return.
-hr_batch_message_line_api.create_message_line
(p_batch_run_number
=> l_batch_run_number
,p_api_name
=>
'hr_person_address_api.create_gb_person_address'
,p_status
=> 'F'
,p_error_number
=> sqlcode
,p_error_message
=> sqlerrm
,p_extended_error_message => fnd_message.get
.
,p_source_row_information => sel.rowid
,p_line_id
=> l_dummy_line_id);
end;
end loop;
-- commit any final rows
commit;
end;
Please Note:
a) A table called HR_API_BATCH_MESSAGE_LINES is provided to be used in the

exceptions section to trap error messages.

SQL> desc hr_api_batch_message_lines
Name
Null? Type
------------------------------- -------- ---LINE_ID
NOT NULL NUMBER(9)
API_NAME
NOT NULL VARCHAR2(61)
BATCH_RUN_NUMBER
NOT NULL NUMBER(9)
STATUS
NOT NULL VARCHAR2(30)
ERROR_MESSAGE
VARCHAR2(512)
ERROR_NUMBER
NUMBER(9)
EXTENDED_ERROR_MESSAGE
VARCHAR2(2000)
SOURCE_ROW_INFORMATION
VARCHAR2(2000)
The column, BATCH_RUN_NUMBER, identifies the batch run. The first cursor in
the above program increments the batch run number for each batch. See also
the exceptions section for raising an error and updating the table. The
table should be cleared out as required.
b) The second cursor,csr_tpa, reads all the addresses from the temporary
table, and then is used in a loop where the API is called for each
record.
c) APIs do not commit records. Therefore, the calling program is counting
the number of records processed and issuing a Commit statement after
every 20.
5. Limitations
-------------------------------------------------------------------------------a) No Query/Read Interface. APIs only perform insert,update and delete
operations.
b) Limited Flexfield support as described in Section 3. This will be
addressed in a future release.
c) APIs are provided for key business processes. There may be some
processes which are not yet covered, but more are added with each new
release.
6. Common Problems
----------------------------------------------------------------------------------This is the main problem that occurs when first encountering APIs. It happens
because a required parameter has been ommitted, or any parameter specified
has been mispelt.
ORA-06550
Line 1, Column n
PLS-00306: Wrong number or types of arguments in call to
<api name>.

Cause: This error occurs if the Style column names without the P_
do not match the API parameters.
Most other errors are specific to the API that is being used. Each API has
it's own validation processes and the data that is being passed must conform...