Oracle HRMS API Frequently Asked Questions

ORACLE Human Resource Management Systems (HRMS)

-----------------------------------------------
API
----------------
FREQUENTLY ASKED QUESTIONS
--------------------------
10-JUL-2001

CONTENTS
--------
1. What is an API?
2. How do I use an API to upload data?
3. Where are APIs located on my system?
4. How do I identify the package name and version of the API?
5. Where can I find information on an API, what it does, and its parameters contained in an API?
6. How do I identify and work with the required parameters for an API?
7. What is the Object Version Number and how do I assign values for it in an API?
8. What is the p_validate Control Parameter?
9. Where may I find information about available APIs in the HR and PAYROLL systems?
10. Can APIs be used in an HR Shared installation?
11. What is the relationship between Initial Balance Upload and Data Pump?
12. When an amployee is terminated using the HR_EX_EMPLOYEE_API, the employee type is not changing
to Ex-Employee.
13. In Release 11i, why is the HR_EX_EMPLOYEE_API looking for a payroll for benefits assignment?
14. What is the difference between the Salary Upload API and the Maintain Salary Proposals API?
15. Can I use an API on an applications table on which an event-based Alert is defined?
16. What is the difference between an API and a publically callable API?

QUESTION & ANSWERS

------------------
1. What is an API?

Answer
------
The Application Programming Interface or API is a PL/SQL packaged procedure which
can be used as an alternative to traditional Application online forms as an entry
point into the Application.

The advantage of using an API as a means of adding data to the system is that you
can enter new information or alter existing data without having to manually enter
the information into the application.

APIs allow users to maintain HRMS information without using Oracle application forms.

APIs insure the integrity of the interrelationship of Oracle Applications tables.

You can modify application information without having to know every feature of the
database structure, and depend on the API to update all the interrelated tables.
Continued use of APIs helps to protect customer-specific data from database structural
changes. As the table structures change, the APIs will be modified with those same
structural changes so that data can continue to be modified without error or need to
update coding.

2. How do I use an API to upload data?

Answer
------
While the API package contains many procedures to insert, update, or delete
application data, the API is not executed on its own. The API must be called, or
executed, by other PL/SQL modules, by a direct SQL*Plus call, or through a front end
such as the Data Pump.

The API package should never be modified for specific custom use. If modified,
Oracle will not be able to support them. If you need additional functionality, APIs
can be used as building blocks, to be called within a more extensive package that
you may build to address the unique functionality you desire.

None of the HRMS APIs issue commits. The calling module should manage the commit of
the transaction. The calling module should also address exception handling and the
actual logging of exceptions to exception tables.
3. Where are APIs located on my system?

Answer
------
For Oracle release 10.7, the APIs are located in the operating system directories:
$PER_TOP/patchsc/107/sql and $PAY_TOP/patchsc/107/sql,
Refer to filenames like pe???bpi.pkh, py???bpi.pkh, and hr???bpi.pkh,
where the ??? represents wildcard characters.

For Oracle release 11 and release 11i, the APIs are located in the operating system
directories:
$PER_TOP/patch/xxx/sql and $PAY_TOP/patch/xxx/sql,
where xxx represents the release 110 or 115.
Refer to filenames like pe???api.pkh, py???api.pkh, and hr???api.pkh,
where ??? represents wildcard characters.

4. How do I identify the package name and version of the API?

Answer
------
To identify the package name of an API as compiled into the Oracle database, in
SQL*Plus enter the following select statement (logged in as APPS)
>SELECT text
FROM all_source
WHERE name like '%your_api_name%' (example: HR_POSITION_API)
AND text like '%Header%';

This will return the header line of the package and package body showing the package
name and current version number.

To compare the version of the API package in your operating system directory to the
one compiled in your database and to check for synchronization, execute the following
from the command line in the API directory:

prompt>strings -a packagename | grep Header

This will return all occurrences of the package, package body and the version
number of the file. Version numbers should match what is compiled in the database.

5. Where can I find information on an API and its parameters?

Answer
------
Review the package header file for the particular API file (.pkh).
6. How do I identify and work with the required parameters for an API?

Answer
------
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. There will be some control parameters that will control processing within
the API but will not map to a database column.

Each parameter name in the API will be prefixed with p_. If the parameter maps to
a database column, the remainder of the name will usually be the same as the table
column name.

When calling an API, you may not need to specify every parameter in the call. It
is optional to assign values to PL/SQL variables with default values specified in
the declaration. Therefore, those parameters without default values specified in
the declaration are considered required parameters and must always be passed in
the API call. Also, any variable tagged as an IN OUT parameter must be included
in the calling parameter list. If you do not wish to assign a value to an IN OUT
parameter, you may assign it a null value.

Those parameters defined with default values may have other values passed as you
determine are needed for your business process. You may wish to compare how the
Oracle Application updates the table to help you decide on overriding the
defaulted parameters.

Finally, if you do not directly assign variables within your API parameter list in
your API call, then number and sequence of parameters must match between the
calling and the called procedures.

7. What is the Object Version Number and how do I assign values for it in an API?

Answer
------
Object Version Number is an assigned number to a row in a database table. When a
new row is inserted, its number is set to 1. As updates are performed on the row,
the object version number is incremented. Object Version Number is transferred
with the row when a query is performed on it. If an update is made to the
transaction and saved back to the table, then the current object version number is
compared with the value being passed back from the transaction.

If the two are the same, the update can be committed to the table. If the two are
different, the update is rejected and flagged with an error. The transaction
should be re-queried, and the update made again to the more current version of the
row.

The API treats object version numbers similarly. Every published API has the
p_object version_number control parameters.
For Create APIs, this parameter is defined as an OUT - the API assigns the object
version number to be 1 for row inserts. For Update APIs, the parameter is defined
as IN OUT. For Update APIs, the object version number is mandatory.

The current value must be passed in the API call and it is compared to the version
on the row in the table. If the versions are different, the error
HR_7155_OBJECT_LOCKED is raised. The information can be re-queried for a more
current version.

8. What is the p_validate Control Parameter?

Answer
------
Every API has a p_validate control parameter. When the parameter is set to FALSE,
all business function validation is performed. If everything is validated, rows
can be inserted, updated, or deleted. Non warning UT parameters, warning OUT
parameters and IN OUT parameters will be returned with set values.

If the parameter is set to TRUE, only the actual operation is validated. A

savepoint is issued at the start of the call and a rollback is done at the end of
the call. 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.
9. Where may I find information about available APIs in the HR and PAYROLL systems?

Answer
------
A list of Oracle supported APIs and information about them can be found online in
the Oracle Application Library in your application.

From the screen menu, navigate to:

Help > Oracle Applications Library > Human Resources >
New Features in this Release > Current APIs
This site will provide information regarding APIs available in your product release.

In addition, the document "Publicly Callable Business Process APIs in Release 11i"
can be found in the HRMS API Toolkit on Metalink.

To find the Toolkit in Metalink navigate:

Technical Libraries > ERP Applications > Human Resource Management Systems >
Human Resources > Functional Information section > API.

This document lists the public APIs as are currently delivered in release 11i.

For more information on these and other API topics, see:

-- "Calling APIs", a technical essay found in the Oracle HRMS UK Implementation
Guide, #A25890-2 in HRMS Product Documentation on Metalink.

-- "Understanding and Using APIs in Oracle HRMS", Document 72310.1, Metalink

-- "Understanding and Using the HRMS Data Pump", Document 72564.1, Metalink

10. Can APIs be used in an HR Shared installation?

Answer
------
In releases 10.7 and 11 the use of APIs is not supported because a Full
installation of HR uses the date tracking capabilities of the HR tables.
Shared installations do not. Since the tables that hold people and
assignment information are date tracked and these are common tables populated
by APIs, there is a real danger of data corruption since tables operate in
Correct mode only.

In release 11i, a new responsibility called HR Foundation has been added to

track employees that are being maintained in other applications where HR is
not installed as Full. Also with the new functionality, several APIs have
been introduced that can now be used safely with other applications. Please
see "HR Foundation and APIs" document in the HRMS API Toolkit on MetaLink.
To find the Toolkit in Metalink navigate:
Technical Libraries > ERP Applications > Human Resource Management Systems >
Human Resources > Functional Information section > API.

This document contains a summarized definition of HR Foundation, a list of

supported APIs, a list of non-supported APIs and a list of APIs to which
special conditions apply.

11. What is the relationship between Initial Balance Upload and Data Pump?

Answer
------
There is no relationship between Initial Balance Upload and Data Pump. They are two
separate processes. Initial Balance Upload is not used with Data Pump at all. Below
you will find a short description of each.

Initial Balance Upload

A procedure used to transfer accumulated seeded and user balance values into Oracle
Payroll for use by implementations. The procedure is usually run from the Concurrent
Manager.
Navigation: HRMS application > Processes and Reports > Submit Processes and Reports >
Initial Balance Upload
Data Pump

A utility which facilitates the loading and updating of data for Oracle HRMS. It does
this by allowing the user to load data from an existing HRMS system into a single
batch interface table using a set of supplied PL/SQL routines that map the data
against the appropriate Application Programming Interface (API). This data can then
be uploaded into the Oracle HRMS system using the Data Pump Engine.

Data Pump Engine

This is a standard concurrent process that performs the data upload.

Navigation: HRMS application > Processes and Reports > Submit Processes and Reports
> Data Pump Engine

12. When an amployee is terminated using the HR_EX_EMPLOYEE_API, the employee type
is not changing to Ex-Employee.

Answer
------
Be sure to date track forward through the application via the date track button to
at least one day past the date that was passed in the API.
13. In Release 11i, why is the HR_EX_EMPLOYEE_API looking for a payroll for benefits
assignment?

Answer
------
When using the HR_EX_EMPLOYEE_API.actual_termination_emp procedure to terminate
employees in Release 11i, the following error message may be received, which
suggests a default payroll for the benefits assignment.

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.

There has been a change to termination functionality in Release 11i. Whenever, an

assignment is terminated, an assignment row of type 'B' is created. This happens
even though Oracle Advance Benefits (OAB) may not be installed. For this reason, a
default monthly payroll needs to be defined on the business group in the Benefits
Defaults area. You must define a default monthly payroll for each business group
you maintain. Benefits assignments are linked to the default monthly payroll in
order to calculate premiums for continuing benefits such as COBRA.

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.

14. What is the Difference between the Salary Upload API and the Maintain Salary Proposals API?

Answer
------
Although both APIs are supported APIs, The Salary Upload API does not support salary admin
approvals. There is no associated security for the API as there is via the application. If
the API allowed salary upload then anyone with SQL*Plus access could approve salary changes.

For this reason, the Salary Maintain Proposal API is the preferred API to use for uploading
salary proposal information.

15. Can I use an API on an applications table on which an event-based Alert is defined?

Answer
------
No, on an applications table that has an event-based Alert defined, the API will error.
To run the API, the Alert will have to be disabled and then re-enabled after the API has
been executed.

16. What is the difference between an API and a publically callable API?

Answer
------
An Application Program Interface is an alternate entry point for data to
be inserted, updated, or deleted from the Application. The Oracle HRMS
Application contains many APIs, but not all of the APIs delivered in
the Application are considered supported, or Publicly Callable APIs.
Publicly Callable APIs are those that engage in validation in the same
manner as the forms do within the application. Validation is performed
in terms of data integrity, insuring that data relationships exist
properly between related tables. Validation is also performed against
business functionality as the application form would enforce it.

Therefore, only Publicly Callable APIs should be used to insert, update

and delete data from the Application.