Application Programmatic Interfaces (APIs) in Oracle HRMS

An Oracle White Paper January 2002

Application Programmatic Interfaces (APIs) in Oracle HRMS

INTRODUCTION

Oracle HRMS uses the Application Programmatic Interface (API) term for a specific application data access method. Professional user access includes a Professional Forms interface; casual users access Oracle HRMS data through a Web-based Self-Service interface. These interfaces allow data manipulation and integrity through code layers and constraints. Direct data manipulation of Oracle HRMS tables causes complex issues in processing and business rules; and is not supported. As an alternative interface, Oracle HRMS delivers APIs: they are a supported means of programmatically manipulating HRMS data. The published HRMS APIs, which are the focus of this paper, comply with database, legislative, business, and user-defined rules for data integrity. Published HRMS APIs are complete packaged procedures that can be called from customer-defined PL/SQL scripts. This flexibility permits customers to create alternative interfaces, such as Web pages, Oracle Forms, and Concurrent Processes, to call HRMS business process APIs. ADE, Data Pump, and delivered Payroll interfaces are Oracle HRMS features that use the same APIs for alternative interfaces.
HRMS Development of APIs

The API initiative began by duplicating critical Form functionality in APIs; however, all Forms were not reworked to use APIs. APIs are used in new development, such as Self-Service HR and Oracle Advanced Benefits (OAB). This distinction is critical for Customers, Consultants, and Support: it means that the same functionality may execute different code from a Form and from the corresponding API.
Customer Extensions

Customer extensions to delivered business rules can be integrated with API callswith the restriction that only the published HRMS APIs manipulate Oracle HRMS data. APIs are frequently used for data conversions, in which large amounts of data in various formats are manipulated and passed to the APIs for uploading into Oracle HRMS. Third-party interfaces also utilize HRMS APIs.

Scope and Audience

This paper provides information to help you understand and use APIs. Use this paper in conjunction with your Oracle HRMS Implementation Guide, Oracle HR or Payroll Users Guide, and the Metalink API Self-Service Toolkit. This paper helps guide you to these sources for further detailed technical essays, examples, and setup information that you need prior to using APIs. The intended audience includes customers and consultants who are technical implementers and developers. Fundamentals of Oracle HRMS and basic knowledge of PL/SQL are assumed, though direction is provided for additional reference.
TERMINOLOGY AND FEATURES Terminology
Terms included in this list may have specific meaning in Oracle HRMS API discussions.

Business Process: a functionally complete process, such as: entering an applicant, hiring or promoting an employee. Publicly Callable APIs or Published APIs: Supported, complete business process APIs. Customers are limited to using the specifically identified and documented HRMS APIs. Row Level: Refers to specific Database table row action or identification. User Hooks: Logic points in APIs, which customers can hook their own custom code, thus extending business rules. Customer Specific Code: a user-defined SQL script to call an API. Because HRMS provides code in layers, the generic term wrapper is avoided, since it can refer to either HRMS delivered or custom scripts.
Naming Conventions

The Oracle HRMS product naming convention includes two and three letter codes: PER, HR, PAY, BEN, FF, and so forth. In most cases, HR is used for objects common to HR and Payroll, PER or PE for Human Resources. API naming conventions are an exception to this generalization: HR is the prefix for most APIs, whether PER or HR entities are involved. User Hook Triggers, discussed later in this paper, have a three part suffix, corresponding to their action. The suffix indicates (1) Before or After; (2) Row or Table; and (3) Insert, Update, or Delete. For example, a trigger that fires before a table is updated has the suffix _BTU; one that fires after a row is inserted has the suffix _ARI.
HRMS BUSINESS PROCESS APPROACH

HRMS Batch Element Entry and Balance initialization interface tables, similar to Open interface tables in other Applications, permit nearly row-level data

entry. APIs contrast to such interfaces because APIs process multiple tables. The tables and their relations are of little concern for the API user: APIs hide the complexity of the database, because they process in complete business functions. APIs are the basis of most interface tools for HRMS, and you will find frequent use for them. APIs process in three functional steps, each of which often involves multiple tables: 1. Business and datetracked rules are confirmed. For example, the API to update an assignment first confirms that the person is an employee on the date specified. 2. Data is validated against business rules. For example, if your setup requires a specific Flexfield or has manual employee numbering, the API call must include those values. 3. The last step is actual data manipulation, pending success of the first two steps.

API Layers

This diagram indicates Published and Internal layers and their relations. Customers can access the two Published layers. Internal layer access is restricted and not supported.

Custom or Alternative Interface Layer Business Process Layer create_employee Business Support Layer Row Handler

Published

create_gb_employee create_us_employee hire_contact

create_default_emp_asg Internal insert/update/delete/lock person, assignment, element entries

Code Layers

APIs have four distinct code layers, as diagrammed above.

Custom / Alternative Interface Layer

The Custom/Alternative Interface Layer is based upon the Business Process Layer, with specific contexts. For example, both employee APIs in the example above include a national identifier: the parameter names vary, corresponding to database column meanings, p_ss_number and p_ni_number.
Business Process Layer

The Business Process Layer corresponds to one business function. Though this layer calls multiple lower layers, it groups their processes as one integrated unit, and the single transaction either succeeds or fails at the Business Process Layer.
Business Support Layer

The Business Support Layer exists when two or more business processes share a processing unit.
Row Handler

Row Handlers contain procedures for data validation and manipulation for a single table.
API User Hooks

API User Hooks refers to points in the API execution to which customers can attach or extend business logic. User-defined code can be hooked into these predefined locations, and executed in conjunction with the API call. User code can: extend validation on Oracle HRMS tables, maintain data in external customer-specific tables (not part of Oracle Applications) simultaneously with the Oracle HRMS updates through the API, or send alerts at particular Oracle HRMS events. The explicit limitation for customer extensions remainsany and all HRMS data manipulation must be performed by HRMS APIs. User Hooks offer similar functionality to the Custom Library, but at the database rather than in the Forms front end. User Hooks allow logic extensions without changing delivered API code. Hooks are regenerated at upgrade. However, since schema changes may occur at any time, all custom procedures should be tested after upgrade. Additionally, API Hooks are available to any interface that calls the API, such as: Forms, SelfService, and Data Pump. Not all HRMS Forms use APIs; a trace can identify whether a Form uses APIs. Only Forms that call APIs will execute a User Hooked code. If the Form does not use APIs, the same code extension can be implemented in Custom Library. The HR_API_HOOKS table holds all available API hooks for APIs in HR_API_MODULES table.
Implementing User Hooks

Four steps are required to implement API User Hooks: 1. Determine the API to which you need to hook extra logic 2. Write the PL/SQL procedure that executes your logic. 3. Register your procedure with one or more specific user hooks.

4. Run the pre-processor program that hooks your PL/SQL procedure to the hook(s). Oracle HRMS has several types of hooks. Only Business Process Hooks correspond to Business Process APIs. They are used when logic must extend beyond the standard business process. Only Business Process Hooks are Supported for Customer use. A list can be obtained by running the following query: select module_name from hr_api_modules where api_module_type='BP';

The $PER_TOP/admin/sql/hrahkpar.sql script provides listing of each API, its hooks, and corresponding procedure parameters. Further details are included in the Metalink Note referenced at the end of this paper.

Publicly Callable APIs

Use only the APIs on the published list of Publicly Callable APIs, available on Metalink and in the latest online Help. These are the only APIs supported for customer use. Data manipulation with non-published APIs may compromise both data integrity and Support agreements. Each HRMS release includes a published list of the Publicly Callable APIs. The current list also includes OTA APIs. You can find the list on Metalink from Top Tech Docs > ERP > HRMS > Human Resources > Extending, Customizing, and System Administration > Custom Library Events and APIs > Publicly Callable Business Process APIs. The same list is also in online Help: (Help) Oracle HRMS > Extend Oracle HRMS > Custom Library Events and APIs > Publicly Callable Business Process APIs
DateTrack Functional Highlights and Restrictions include:

Functional constraint: For example, when converting an ex-employee: a person cannot be entered into the Forms as an ex-employee; likewise, a person who had an active assignment should be converted as an employee with the appropriate date, and then updated by use of the termination API and the appropriate date. DateTrack modes are restricted by logic similar to the Forms.

DateTrack Effective Date: APIs do not restrict the effective_date, forcing it to be different than the effective_end_date. Forms enforce that restriction; APIs allow the same value for the effective date and effective_date_date. DateTrack relational restrictions are similar in APIs and Forms. For example, to relate two entities with different effective_start_dates, you must first enter the earlier entity, then the later entity. You can establish the relation on either entity, as required. Examples include: an assignment with a supervisor who has a later start date; a job updated with a more recently established grade, and so forth.
API Source

Core product API package header and package body scripts are located in the product TOP admin/sql directories, such as $PER_TOP. Refer to filenames such as *api.pkh or *api.pkb to find API package headers and body. For example, the hr_employee_api package header can be found in the $PER_TOP/admin/sql/peempapi.pkh file." Localization-specific APIs follow a *LLi.pkh naming standard, where LL is the two letter localization code. If you simply want a list of PL/SQL parameters, use SQL*Plus to describe the API, using the database package name, period, and the name of the API. This is the equivalent of opening the package header. For example, to list the parameters for the create_grade_rate_value API, enter the following: SQL> describe hr_grade_api.create_grade_rate_value
API Parameters

Certain parameters are common to all Publicly Callable APIs. These are listed with a brief description of their functionality. More information and examples are available in the Technical Essay, APIs in Oracle HRMS, in the Implementing HRMS Guide, the complete PDF file is available on Metalink. These parameters are also discussed in the HRMS API Self-Service ToolKit FAQ, available on Metalink.
Validate Control

P_Validate: controls validation, a Boolean flag for which TRUE determines that only validation occurs, and FALSE determines that validation and data manipulation occur. The default is FALSE. However, no changes are committed until you explicitly commit, or implicitly commit, by exiting SQL*Plus.
DateTrack Mode

P_Date_Track_Mode, refers to the possible DateTrack Modes permitted by the business process and data. APIs will return error messages if you attempt to use an invalid or unavailable DateTrack mode.
Object Version Number

P_Object_Version_Number is the mechanism for controlling multiple user access to records and rows. This parameter acts similarly to the Forms locking mechanism. The current value of the OVN must be passed to the API, you can Select the MAX(Object_version_number) from the entity table(s) that your API processes. This parameter depends on existing records; its inclusion varies with API type, such as create or update.
Multi Language Support (MLS) Control

P_Language_Code is the parameter supporting Multi Language Support (MLS). A call to an MLS API inserts business process data, and maintains one row in a _TL (translation layer) table, updating the source_lang and language_code columns, relating to the FND_LANGUAGES table.. The default language code is equivalent to: select userenv(LANG) from dual;
Unique Parameters

Each API also has unique parameters, corresponding to the entities in the business process. Most of these parameters are named similarly to table columns or Form fields. Parameters for each API are documented in the API package header. You can view or spool this file and use it as reference when creating calls to APIs.
CALLING APIS

If you have extracted data from the Application using Application Data Exchange (ADE), you can upload revised data directly through an API call. Normally, however, your data will be in an Oracle database table external to the HRMS application, or completely external to the system, such as from a thirdparty interface.
Preparing Data for Upload

Oracle HRMS does not provide staging tables for data that is to be input to the APIs. These tables will vary with each project or interface. You may need to decode incoming data in preparation for passing it to the APIs. You can prepare the data at any stage before passing it to the API. You can use a tool such as SQLLoader to load data into staging tables.

Customer Scripts

Spooling the API package header and editing in Notepad is a simple way to prepare a script for calling an API. You can declare your local variables and cursors, call the API, and then include Exception and Commit processing.

Testing

APIs can be tested without making permanent data changes by using the p_validate parameter. Normally the customer scripts calling APIs will have extensive logic, to identify the appropriate setup entities and pass their _ids to the API as local parameters. If there are issues calling an API, the first step is to create the simplest possible calling script with hard-coded parameter values. This will eliminate errors introduced in the script logic. As noted earlier, HRMS Forms do not necessarily execute the same code. However, if an error occurs from an API call, it is useful to attempt the same process, with the same data, in the Forms Professional Interface.
Commit and Rollback

When an API is called, either the entire transaction is successful, and all the individual database changes will be applied; or, the transaction fails and no changes can be made to the database. APIs do not include commit or rollback, regardless of validation mode. Logic to specify commit or rollback is user responsibility. You can include logic in your calling script to specify record count or conditions.
API PL/SQL Exceptions

Because APIs execute multiple code layers, your code to the API should handle Exceptions. The following example can be adapted to produce troubleshooting messages. Exception when others; hr_batch_message_line_api.create_message_line (p_batch_run_number => l_batch_run_number ,p_api_name=><hr_xxx_api.api_procedure> ,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

If your call to the API fails, you can view the error messages in HR_API_BATCH_MESSAGE_LINES tables with the following query:

select * from hr_api_batch_message_lines abm where abm.batch_run_number = :batch_run_number order by abm.line_id;

Additional Usage Notes

APIs are available for primary business processes throughout HRMS. Recent Oracle HRMS products, such as Oracle Advanced Benefits (OAB) and SelfService HR (SSHR), use APIs for nearly all functionality. Additional HRMS product features and functions using APIs are fully documented. This section highlights API usage of those product features. Complete reference information is included at the end of this paper.
Oracle Government HR (GHR)

Oracle Government HR (GHR) uses APIs with an interface that simulates specific U.S. government forms: APIs are called in Validate mode, as Oracle Workflow routes the Forms. The data remains in intermediary tables until approvals are completed. Then, the API is called with the Validate parameter set to False, moving data to Oracle HRMS tables and completing the business process transaction.
Application Data Exchange (ADE)

Application Data Exchange (ADE) can call APIs to upload data to the Oracle HRMS system. ADE uploads rely on previously extracted HRMS data. For that reason, ADE cannot be used for initial data loading (API create or insert mode). When you identify an API name in the ADE upload window, the list of parameters is provided. You can select from the parameters to format extracts and uploads.
Data Pump

Data Pump is available for many published APIs. The list of publicly callable APIs has a column indicating Data Pump support. Data Pump creates views for supported APIs, enabling user key definition. This reduces your need to manage many _ids used by the APIs.

10

HR Data Uploader (HRDU)

HR Data Uploader (HRDU) processes data that is exported from a spreadsheet, moving it into Data Pump tables. This utility uses predefined keys for specific applications. The result is that the user needs to run only the Data Pump process. HRDU is used in the Payroll Interface Kit and for loading the OTA SkillScape Dictionary.
Batch Creation of User Accounts

Creating user accounts through a batch process is enabled by the hr_user_acct_api. This API is designed to expedite creating user accounts for employees, particularly useful for Self-Service implementation, where thousands of employees may require user accounts. This functionality integrates several features: APIs, Data Pump, Concurrent Processes, and API User Hooks. Several steps are required when using the hr_user_acct_api: API User Hook logic must be defined and registered. The logic includes format for user names, default passwords, and responsibilities. A concurrent program, User Account Employee Extract progress, is run to extract a batch file for user accounts. The Data Pump Engine is used to create rows, using HR_PUMP_BATCH_HEADERS and HR_PUMP_BATCH_LINES. When Data Pump calls the API, it uses views that correspond to the concurrent process run type: initially user accounts may be created for all employees, using the Create User Account New Hires process. Other modes include inactivating user accounts for termination, and update user account. For complete details, please see the White Paper, Batch Creation of User Accounts, referenced at the end of this paper.
Release 10.7

Release 10.7 Specific Usage Note: Forms 4.5.7 APIs have restrictions on default values, forcing users to include every parameter in calls APIs. If any parameter is not specified then Forms raises a misleading error message when the API is called.
API Flexfield Validation

Summary of when automatic Flexfield validation is included as part of the API: R10SC: Never automatic R11.0: Only automatic from R11.0 Patchset D, onwards.

11

R11i: Always automatic.

From Release 11.0.2 forward, supported APIs provide user hook and Flexfield validation. However, APIs imply certain restrictions to validation and Value Sets. For example, Value Sets or validation referencing a Form field will fail because the field value is inaccessible to the API. API and Flexfield value set validation referencing the following items can result in problems: User profile options Form block.field items A row in the FND_SESSIONS database table For complete details and recommended solutions, see the essay on Validation of Flexfield Values in the Release 11i Implementation Guide (Technical Essays, chapter) also available through Metalink patch 960733.
EXAMPLES

These examples demonstrate how to call APIs. Examples 1 and 2 each indicate a single call to the Create and Update Address APIs. Example 3 demonstrates the Create Address API called in a loop. For more detail, please see PL/SQL references noted at the end of this paper.
Example 1Create Style API

l_object_version_number l_address_id

number; number;

begin

hr_person_address_api.create_us_person_address (p_validate ,p_effective_date ,p_person_id ,p_primary_flag ,p_date_from ,p_address_line1 ,p_city => => => => => => => false trunc(sysdate) 1103 'Y' trunc(sysdate) '123 Front Harbor' Annapolis

12

,p_state ,p_zip ,p_county ,p_country ,p_address_id ,p_object_version_number l_object_version_number ); end;

=> MD => 21400 => Anne Arundel => 'US'

=> l_address_id =>

Example 2Update Style API

declare

l_object_version_number

number;

cursor csr_address is select max(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_us_person_address (p_validate ,p_effective_date 2001','dd-mon-yyyy') ,p_address_id => false => to_date('17-Nov=> 323

13

,p_address_line2

=> 'Building 2'

,p_object_version_number => l_object_version_number ); end;

Example 3PL/SQL Batch Program

This demonstrates using a PL/SQL cursor to call an API in a programmatic loop. The column, BATCH_RUN_NUMBER column is used in the Exceptions section. The first cursor increments the batch number. The second cursor,csr_tpa, reads all the addresses from a customer-defined temporary or staging table, then is calls the API for each record. This example processes a commit statement after processing each set of 20 records. The calling script must handle commits.

declare -l_rows_processed -- rows processed by api l_commit_point number := 20; number := 0;

-- Commit after X successful rows l_batch_run_number l_dummy_line_id l_address_id l_object_version_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 US address rows number; number; number; number;

14

-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.city , tpa.county , tpa.zipcode , tpa.country , 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_us_person_address (p_validate ,p_effective_date => true => sel.date_from

15

,p_person_id ,p_primary_flag ,p_date_from ,p_address_type ,p_address_line1 ,p_address_line2 ,p_address_line3 ,p_city ,p_state ,p_county ,p_zip ,p_country ,p_address_id

=> sel.person_id => sel.primary_flag => sel.date_from => sel.address_type => sel.address_line1 => sel.address_line2 => sel.address_line3 => sel_city => sel_state => sel.county => sel.zipcode => sel.country => 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: Since an error has occurred only the work in the last API call is implicitly rolled back. The uncommitted work from previous API calls is not affected.

16

If the error is ora-20001 the fnd_message.get function retrieves and substitutes all tokens for the short and extended message text. If the error is not ora-20001 null is returned. */ hr_batch_message_line_api.create_message_line (p_batch_run_number ,p_api_name => l_batch_run_number =>

'hr_person_address_api.create_us_person_address' ,p_status ,p_error_number ,p_error_message => 'F' => sqlcode => 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; =>

Exception Processing

Errors in APIs need to be captured. The HR_API_BATCH_MESSAGE_LINES table holds Exception error messages.

SQL> desc hr_api_batch_message_lines Name Null? Type

------------------------------- -------- ---LINE_ID API_NAME BATCH_RUN_NUMBER STATUS NOT NULL NUMBER(9) NOT NULL VARCHAR2(61) NOT NULL NUMBER(9) NOT NULL VARCHAR2(30)

17

ERROR_MESSAGE ERROR_NUMBER EXTENDED_ERROR_MESSAGE SOURCE_ROW_INFORMATION

ERRORS

VARCHAR2(512) NUMBER(9) VARCHAR2(2000) VARCHAR2(2000)

Metalink API Troubleshooting Guides refer to common errors. One note of particular interest to new API users is Metalink Note: 152253.1, Subject: Troubleshooting Guide for HRMS API Errors - PLS-306. The error has a simple solution, but can be frustrating to locate: ORA-06550 Line <n>, Column <nn> PLS-00306: Wrong number or types of arguments in call to <api name>. Line <n> refers to the line number that actually calls the API. One line number refers to the call, including its list of parameters and values. This error can be caused by: a typographical error, a missing required parameter, a wrong data type, or a value for a parameter that should be null.
REFERENCES

API Technical Essays are available in the Implementing Oracle HRMS Guides, available on Metalink from Top Tech Docs > ERP > HRMS > Human Resources. Select your appropriate Release, then either Global or your legislation. Validation of Flexfield Values in the Release 11i Implementation Guide (Technical Essays, chapter) also available through Metalink patch 960733). User Guides available from Metalink > ERP > HRMS. Follow the specific product link to Documentation. Oracle Human Resources User Guide Oracle Payroll User Guide Oracle Training Administration User Guide

How to Find a List of Publicly Callable Business Process APIs for Oracle Human Resources (HRMS) and Oracle HR Foundation in Release 11i, Type: Note, Doc ID: 157505.1 PL/SQL: Metalink > Top Tech Docs > Internet Developer Tools. Under the Programmatic Interfaces folder, select PL/SQL. Documentation, White Papers, How-to articles, and Sample Code are available. API User Hooks, Metalink Note Doc ID :73170.1

18

Understanding and Using the HRMS Data Pump, Metalink Note Doc ID: 72564.1 Overview of Steps Required to Implement Application Data Export (ADE) Note Doc ID: 134724.1 Create User API: Metalink > Top Tech Docs > HRMS > Oracle Human Resources > White Papers > Functional Issues: Batch Creation of User Accounts Data Pump: Metalink > Top Tech Docs > HRMS > Oracle Human Resources > White Papers > Technical Issues: Oracle HRMS Data Pump

19

Application Programmatic Interfaces (APIs) in Oracle HRMS January 2002 Author:Jeanne Cecil Contributing Authors: Peter Attwood, Steven McMillan Copyright Oracle Corporation 2002 All Rights Reserved Printed in the U.S.A. This document is provided for informational purposes only and the information herein is subject to change without notice. Please report any errors herein to Oracle Corporation. Oracle Corporation does not provide any warranties covering and specifically disclaims any liability in connection with this document. Oracle is a registered trademark and Enabling the Information Age, [Add of Oracle Corporation.

trademarks here] are trademarks

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: 650.506.7000 Fax 650.506.7200 Copyright Oracle Corporation 2002 All Rights Reserved

20