Hi All,
Happy Diwali :)
I would like to give you some idea on Oracle User hooks.
You might have come across situations wherein we must modify the Oracle standard API to get some info into custom tables/extra validations/to send alerts/etc. However, Oracle doesn’t recommend modifying the standard API.
What is API?
API, an abbreviation of Application Program Interface, is a set of routines, protocols, and tools for building software applications. The API specifies how software components should interact and APIs are used when programming graphical user interface (GUI) components.
What is User Hook?
User Hook, is a pl/sql code used to execute from the standard API.
Oracle has supplemented the core product API functionality by the addition of API user hooks.
When the API processing reaches a user hook, core product processing stops and any customer specific logic for that event is executed. Then, if no errors occur, the main API processing resumes.
You can use such extra logic to add functionality not supplied directly by Oracle Applications.
NOTE: You should not manually edit the API source code files supplied by Oracle If you do modify these codes, Oracle Applications will be unable to support the product, and upgrades may not be possible. Oracle Applications only supports direct calls to the published APIs. Direct calls to any other server-side package procedures or functions that are written as part of the Oracle HRMS Applications suite are not supported.
Hence, the conclusion is User hook is used to add extra logic to the Business APIs using User Hooks
Below diagram shows the overview of how the custom logic executes in the Oracle standard API:
User Hook Tables:
HR_API_HOOKS - Contains all the API hooks
HR_API_MODULES – Module list in which hooks available
Steps to Implementing User Hooks:
There are basically 4 steps to implementing API User Hooks.
1. Choose the API you wish to hook some extra logic to.
2. Write the PL/SQL procedure that you wish to be called by the hook.
3. Register or associate the procedure you have written with one or more specific user hooks.
4. Run the pre-processor program which builds the logic to execute your PL/SQL procedure from the hook specified in 3.
Note: Oracle has not given the user hook option to all the forms OR APIs.
HR_API_HOOKS table gives the hook details
Use HR_API_MODULES table to get the API names (Module Package) and the procedure name (Module Name) with respective Module Type.
A list of each API, it's hooks, and the parameters available to a procedure called by that hook, can be obtained by running the script
$PER_TOP/admin/sql/hrahkpar.sql.
TYPES of User Hook:
There are 5 different types of User Hooks (Module Type in the HR_API_MODULES):
> Business Process APIs:
1. AD – After Delete
2. AI – After Insert
> Row Handler APIs:
1. AP – After Process
2. AU – After Update
3. BP – Before Process
Example:
Business Process User Hooks:
The Business Process hooks should be used if extra logic is required on top of the standard business process logic. For instance, CREATE_EMPLOYEE, UPDATE_ELEMENT_ENTRY,etc.
A full list can be obtained by running the following script:
SELECT module_name
FROM hr_api_modules
WHERE api_module_type='BP'
The two types of Business Process hook available are:
Before Process - These hooks execute logic before the main API logic. The majority of validation will not have taken place. No database changes will have been made.
After Process - These hooks will execute after the main API validation has completed and database changes made. If the main validation failed then the user hook will not be called.
The following sql retrieves the hook details of the After Process hook for the CREATE_EMPLOYEE business process.
SELECTahk.api_hook_id,
ahk.api_module_id,
ahk.hook_package,
ahk.hook_procedure
FROM hr_api_hooks ahk,
hr_api_modules ahm
WHERE ahm.module_name='CREATE_EMPLOYEE'
and ahm.api_module_type = 'BP'
and ahk.api_hook_type = 'AP'
and ahk.api_module_id=ahm.api_module_id;
Row Handler User Hooks:
The Row Handler hooks should be used if extra logic is required prior to
performing an Insert,Update or Delete on a specific table. As all the main APIs
call the row handlers, these hooks would be executed by any API that updates
the specific table.
A full list of the Row Handler APIs can be obtained by running the following sql:
SELECT module_name
FROM hr_api_modules
WHERE api_module_type='RH';
The following sql retrieves hook details for the After Insert hook for the PER_ALL_PEOPLE_F table:
SELECT ahk.api_hook_id,
ahk.hook_package,
ahk.hook_procedure
FROM hr_api_hooks ahk,
hr_api_modules ahm
WHERE (ahm.module_name='PER_ALL_PEOPLE_F'
OR ahm.module_name='PER_PEOPLE_F')
AND ahm.api_module_type = 'RH'
AND ahk.api_hook_type = 'AI'
AND ahk.api_module_id=ahm.api_module_id;
Core Product Logic
Core Product Logic is split into a number of components. For tables that can be altered
by an API there is an internal row handler code module. These rows handlers are
implemented for nearly all the tables in the system where APIs are available. They
control all the insert, update, delete and lock processing required by the main APIs. For
example, if a main API needs to insert a new row into the PER_ALL_PEOPLE_F table it
will not perform the DML itself. Instead it will execute the PER_ALL_PEOPLE_F row handler
Using User Hooks
After choosing the type of hook required and the location for it, the hook code
has to be written. It then needs to be registered, and finally the hook package
has to be modified to call it. The example used in this section describes the
implementation of an After Process hook in the CREATE_EMPLOYEE Business Process API.
Writing the custom PL/SQL procedure
The hook code must be written in a PL/SQL server-side package procedure. The
procedure is always called if registered (unless the main validation logic
errors first), and, any conditional logic must be implemented in the code
and an application error raised if required.
NOTE: No commits or rollbacks are allowed in the hook procedure. These are always
performed after the API has been called whether it be in a PL/SQL wrapper or
form.
When the PL/SQL package has been created, it must be compiled successfully
on the database.
Example:
CREATE OR REPLACE PACKAGE scoop_nationality_check AS
PROCEDURE polish_name_check
(p_last_name in VARCHAR2
,p_nationality in VARCHAR2);
END scoop_nationality_check;
/
CREATE OR REPLACE PACKAGE BODY scoop_nationality_check AS
PROCEDURE polish_name_check
(p_last_name in VARCHAR2
,p_nationality in VARCHAR2)
IS
BEGIN
-- When the first name entered is a polish name then check that the
-- nationality entered is Polish
IF p_last_name = 'Chrosicka' THEN
IF p_nationality != 'POL' THEN
dbms_standard.raise_application_error (num => -20999
,msg => 'Nationality must be Polish');
END IF;
END IF;
END polish_name_check;
END scoop_nationality_check;
/
Registering the User Hook
The next step is to link the custom package procedure created above
DECLARE
l_api_hook_call_id NUMBER;
l_object_version_number NUMBER;
BEGIN
hr_api_hook_call_api.create_api_hook_call
(p_validate => FALSE,
p_effective_date => TO_DATE('01-JUL-1999','DD-MON-YYYY'),
p_api_hook_id => 63,
p_api_hook_call_type => 'PP',
p_sequence => 3000,
p_enabled_flag => 'Y',
p_call_package => 'SCOOP_NATIONALITY_CHECK',
p_call_procedure => 'POLISH_NAME_CHECK',
p_api_hook_call_id => l_api_hook_call_id,
p_object_version_number => l_object_version_number);
EXCEPTION WHEN OTHERS
DBMS_OUTPUT.PUT_LINE(SUBSTR(SQLERRM,1,300)); -- Handle exception
END;
Points to be noted:
a. See section ‘Business Process User Hooks’ to get api_hook_id. (Refer above queries)
b. The hook mechanism only supports calls to package procedures currently
so api_hook_call_type must be PP.
c. Sequence numbers > 2000 are recommended, as sequences < than 2000 are
reserved for Oracle seeded logic which needs to be processed first.
Please note that you can add any number of hooks to the same API, and
order them using the sequence.
To Delete the user hook:
DECLARE
l_api_hook_call_id NUMBER := 2;
l_object_version_number NUMBER := 3;
BEGIN
hr_api_hook_call_api.delete_api_hook_call
(p_validate => FALSE,
p_api_hook_call_id => l_api_hook_call_id,
p_object_version_number => l_object_version_number);
EXCEPTION WHEN OTHERS
DBMS_OUTPUT.PUT_LINE(SUBSTR(SQLERRM,1,300)); -- Handle exception
END;
The above call is deleting a specific user hook. Please note any changes made to the HR_API_HOOK_CALLS table, be they via the supplied procedures or not,
will only be effective once the pre-processor has been run.
Running the Pre-Processor
Adding rows to the HR_API_HOOK_CALLS table by itself is not sufficient to
enable this extra logic to be called. The pre-processor program must be called
first. This will look at the definitions in the table and build another package
body in the database which is known as the hook package body.
If successful, the pre-processor will hard code the calls to the custom package procedures into the hook package body. If no extra logic is implemented the hook package body is
still created but without any calls to custom procedures.
During upgrades the pre-processor program will be automatically called to create
the hook package bodies.
To run the pre-processor run one of the following commands:
cd $PER_TOP/admin/sql
Log into SQLPLUS as the APPS user
SQL> @hrahkall.sql
OR
SQL> @hrahkone.sql
NOTE: The first script will create all hook package bodies, whilst the second will create hook package bodies for one API module only, and prompt for that api_module_id. Refer to the results of the query executed in above(first query) to obtain the api_module_id.
Tips on resolving Invalid Hook Packages
Occasionally when applying patches Hook Packages may fail to compile. This could
be for a variety of reasons. Running the report $PER_TOP/patch/115/sql/hrahkall.sql
will provide a comprehensive list of the invalid hook packages.
Sometimes the problem may simply be resolved by reapplying the hook package
Refer HRMS Implementation guide for examples
To find the code used by a User Hook
You can use the hook name and type from the error message:
SELECT api_hook_id, hook_procedure
FROM hr_api_hooks
WHERE api_hook_type = 'AP'
AND hook_procedure LIKE 'UPDATE_ORG_INFORMATION%';
SELECT call_package, call_procedure, legislation_code
FROM hr_api_hook_calls
WHERE api_hook_id = 5012; -- Got this value from the above query
The following query will provide you the additional information:
SELECT *
FROM hr_api_hook_calls
WHERE api_hook_id IN (SELECT api_hook_id
FROM hr_api_hooks
WHERE api_module_id = (SELECT api_module_id
FROM hr_api_modules
WHERE module_name LIKE 'UPDATE_ORG_INFORMATION%'));
*************************************************************************************************
Please refer the below unpublished metalink note OR HRMS implementation guide for more info on User hooks:
> Understanding and Using Application Program Interface (API) User Hooks in Oracle HRMS [ID 73170.1]
> Refer ‘API User Hooks’ section in Oracle HRMS Implementation Guide
List of APIs
The following APIs support all the API event points (Before process; After process) :
applicant assignment
offer_apl_asg
update_apl_asg
contact relationship
create_contact_relationship
delete_contact_relationship
employee
actual_termination_emp
final_process_emp
create_employee
employee assignment
activate_emp_asg
suspend_emp_asg
final_process_emp_asg
update_emp_asg
actual_termination_emp_asg
employee assignment criteria
update_emp_asg_criteria
grade rate value
create_grade_rate_value
update_grade_rate_value
delete_grade_rate_value
job requirement
create_job_requirement
mass moves
mass_moves
pay scale value
create_pay_scale_value
update_pay_scale_value
delete_pay_scale_value
person address
create_person_address
update_person_address
personal payment method
create_personal_payment_method
update_personal_payment_method
position
create_position
update_position
position requirement
create_position_requirement
secondary applicant assignment
create_secondary_apl_asg
secondary employee assignment
create_secondary_emp_asg
Row Handlers
The Row Handlers on the following tables support all the Row Handler event points (After insert; After update; After delete) :
PER_ADDRESSES
PER_ALL_PEOPLE_F
PER_ALL_ASSIGNMENTS_F
PAY_PERSONAL_PAYMENT_METHODS_F
PER_POSITIONS
PER_APPLICATIONS
PER_CONTACT_RELATIONSHIPS
This document is for my future reference and posting for others to share the knowledge. Please do suggest or comment which helps all.
Thank you.
Regards,
Rajesh