User Hook Concepts
There are many times where we need put some extra logic before or after happening of some business event. In Such cases, we use user hook API. It is a functionality provided in Oracle HRMS through which you can have more control on application w.r.t implementing business rules.
How it Works:
In Oracle HRMS, Oracle has provided location in HRMS APIs, where customer can put his business logic. When API processing reaches a user hook, core product processing stops and any customer specific logic for that event is executed. After processing of customer specific logic, main API resumes its processing. These are normally used in scenarios where we want to put extra logic to add
functionality not supplied directly by Oracle. This could include business events like
1. Validate Data is EIT before or after insertion either through self service or core HR
2. Validate Data is SIT before or after insertion either through self service or core HR
3. Validating particular customer data: For example, you could limit grade step promotions to a
maximum of one step.
4. Maintaining additional data in your own user defined tables
5. Detecting that a particular business event has occurred: If the event was an employee termination process, for example, this could be made to send a message to your security database disabling the employee’s security pass.
Attention: 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.
Note: All Oracle HRMS forms does not use HRMS APIs, User hook can be implemented for only those forms which perform functions through API. The HR_API_HOOKS table holds all available API hooks for APIs in HR_API_MODULES table.
Implementation Steps For User Hooks
Four steps are required to implement API User Hooks:
1. Identifying the correct User Hook API where you want to put your custom logic
2. Create PL/SQL procedure to execute 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).
Lets Assume we want to put a logic to stop a user if he applied annual leave more than 30 days. It should validate before Absence Creation. So we have to perform following steps in sequence
Step 1 – Identifying the correct User Hook API
SELECT ahk.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 like ‘%_PERSON_ABSENCE%’
AND ahm.api_module_type = ‘BP’
AND ahk.api_hook_type = ‘AP’
AND ahk.api_module_id = ahm.api_module_id
It will show all Person Absence relevant APIs.We need to select the correct API that matched with our requirement. For Example for above mentioned requirement, we shall select CREATE_PERSON_ABSENCE_A API. We shall note its API_HOOK_ID (3840) and API_MODULE_ID (1731) as API_HOOK_ID will be used at the time of registration of user hook mentioned in Step 3 ahead and API_MODULE_ID will be needed in running the processor in Step 4.
Step 2. Create PL/SQL procedure to execute your logic.
CREATE OR REPLACE PACKAGE APPS.LSG_USERHOOK_PKG
AS
PROCEDURE XXALB_CREATE_ABS_VAL_P
(P_EFFECTIVE_DATE IN DATE
,P_PERSON_ID IN NUMBER
,P_BUSINESS_GROUP_ID IN NUMBER
,P_ABSENCE_ATTENDANCE_TYPE_ID IN NUMBER
,P_ABS_ATTENDANCE_REASON_ID IN NUMBER
,P_COMMENTS IN LONG
,P_DATE_NOTIFICATION IN DATE
,P_DATE_PROJECTED_START IN DATE
,P_TIME_PROJECTED_START IN VARCHAR2
,P_DATE_PROJECTED_END IN DATE
,P_TIME_PROJECTED_END IN VARCHAR2
,P_DATE_START IN DATE
,P_TIME_START IN VARCHAR2
,P_DATE_END IN DATE
,P_TIME_END IN VARCHAR2
,P_ABSENCE_DAYS IN NUMBER
,P_ABSENCE_HOURS IN NUMBER
,P_AUTHORISING_PERSON_ID IN NUMBER
,P_REPLACEMENT_PERSON_ID IN NUMBER
,P_ATTRIBUTE_CATEGORY IN VARCHAR2
,P_ATTRIBUTE1 IN VARCHAR2
,P_ATTRIBUTE2 IN VARCHAR2
,P_ATTRIBUTE3 IN VARCHAR2
,P_ATTRIBUTE4 IN VARCHAR2
,P_ATTRIBUTE5 IN VARCHAR2
,P_ATTRIBUTE6 IN VARCHAR2
,P_ATTRIBUTE7 IN VARCHAR2
,P_ATTRIBUTE8 IN VARCHAR2
,P_ATTRIBUTE9 IN VARCHAR2
,P_ATTRIBUTE10 IN VARCHAR2
,P_ATTRIBUTE11 IN VARCHAR2
,P_ATTRIBUTE11 IN VARCHAR2
,P_ATTRIBUTE12 IN VARCHAR2
,P_ATTRIBUTE13 IN VARCHAR2
,P_ATTRIBUTE14 IN VARCHAR2
,P_ATTRIBUTE15 IN VARCHAR2
,P_ATTRIBUTE16 IN VARCHAR2
,P_ATTRIBUTE17 IN VARCHAR2
,P_ATTRIBUTE18 IN VARCHAR2
,P_ATTRIBUTE19 IN VARCHAR2
,P_ATTRIBUTE20 IN VARCHAR2
,P_PERIOD_OF_INCAPACITY_ID IN NUMBER
,P_SSP1_ISSUED IN VARCHAR2
,P_MATERNITY_ID IN NUMBER
,P_SICKNESS_START_DATE IN DATE
,P_SICKNESS_END_DATE IN DATE
,P_PREGNANCY_RELATED_ILLNESS IN VARCHAR2
,P_REASON_FOR_NOTIFICATION_DELA IN VARCHAR2
,P_ACCEPT_LATE_NOTIFICATION_FLA IN VARCHAR2
,P_LINKED_ABSENCE_ID IN NUMBER
,P_BATCH_ID IN NUMBER
,P_CREATE_ELEMENT_ENTRY IN BOOLEAN
,P_ABS_INFORMATION_CATEGORY IN VARCHAR2
P_ABS_INFORMATION1 IN VARCHAR2,
P_ABS_INFORMATION1 IN VARCHAR2,
P_ABS_INFORMATION2 IN VARCHAR2,
P_ABS_INFORMATION3 IN VARCHAR2,
P_ABS_INFORMATION4 IN VARCHAR2,
P_ABS_INFORMATION5 IN VARCHAR2,
P_ABS_INFORMATION6 IN VARCHAR2,
P_ABS_INFORMATION7 IN VARCHAR2,
P_ABS_INFORMATION8 IN VARCHAR2,
P_ABS_INFORMATION9 IN VARCHAR2,
P_ABS_INFORMATION10 IN VARCHAR2,
P_ABS_INFORMATION11 IN VARCHAR2,
P_ABS_INFORMATION12 IN VARCHAR2,
P_ABS_INFORMATION13 IN VARCHAR2,
P_ABS_INFORMATION14 IN VARCHAR2,
P_ABS_INFORMATION15 IN VARCHAR2,
P_ABS_INFORMATION16 IN VARCHAR2,
P_ABS_INFORMATION17 IN VARCHAR2,
P_ABS_INFORMATION18 IN VARCHAR2,
P_ABS_INFORMATION19 IN VARCHAR2,
P_ABS_INFORMATION20 IN VARCHAR2,
P_ABS_INFORMATION21 IN VARCHAR2,
P_ABS_INFORMATION22 IN VARCHAR2,
P_ABS_INFORMATION23 IN VARCHAR2,
P_ABS_INFORMATION24 IN VARCHAR2,
P_ABS_INFORMATION25 IN VARCHAR2,
P_ABS_INFORMATION26 IN VARCHAR2,
P_ABS_INFORMATION27 IN VARCHAR2,
P_ABS_INFORMATION28 IN VARCHAR2,
P_ABS_INFORMATION29 IN VARCHAR2,
P_ABS_INFORMATION30 IN VARCHAR2,
,P_ABSENCE_CASE_ID IN NUMBER
);
END LSG_USERHOOK_PKG;
/
CREATE OR REPLACE PACKAGE BODY APPS.LSG_USERHOOK_PKG
PROCEDURE LSG_CREATE_ABS_VAL_P (
P_EFFECTIVE_DATE IN DATE,
P_PERSON_ID IN NUMBER,
,P_BUSINESS_GROUP_ID IN NUMBER
,P_ABSENCE_ATTENDANCE_TYPE_ID IN NUMBER
,P_ABS_ATTENDANCE_REASON_ID IN NUMBER
,P_COMMENTS IN LONG
,P_DATE_NOTIFICATION IN DATE
,P_DATE_PROJECTED_START IN DATE
,P_TIME_PROJECTED_START IN VARCHAR2
,P_DATE_PROJECTED_END IN DATE
,P_TIME_PROJECTED_END IN VARCHAR2
,P_DATE_START IN DATE
,P_TIME_START IN VARCHAR2
,P_DATE_END IN DATE
,P_TIME_END IN VARCHAR2
,P_ABSENCE_DAYS IN NUMBER
,P_ABSENCE_HOURS IN NUMBER
,P_AUTHORISING_PERSON_ID IN NUMBER
,P_REPLACEMENT_PERSON_ID IN NUMBER
,P_ATTRIBUTE_CATEGORY IN VARCHAR2
,P_ATTRIBUTE1 IN VARCHAR2
,P_ATTRIBUTE2 IN VARCHAR2
,P_ATTRIBUTE3 IN VARCHAR2
,P_ATTRIBUTE4 IN VARCHAR2
,P_ATTRIBUTE5 IN VARCHAR2
,P_ATTRIBUTE6 IN VARCHAR2
,P_ATTRIBUTE7 IN VARCHAR2
,P_ATTRIBUTE8 IN VARCHAR2
,P_ATTRIBUTE9 IN VARCHAR2
,P_ATTRIBUTE10 IN VARCHAR2
,P_ATTRIBUTE11 IN VARCHAR2
,P_ATTRIBUTE11 IN VARCHAR2
,P_ATTRIBUTE12 IN VARCHAR2
,P_ATTRIBUTE13 IN VARCHAR2
,P_ATTRIBUTE14 IN VARCHAR2
,P_ATTRIBUTE15 IN VARCHAR2
,P_ATTRIBUTE16 IN VARCHAR2
,P_ATTRIBUTE17 IN VARCHAR2
,P_ATTRIBUTE18 IN VARCHAR2
,P_ATTRIBUTE19 IN VARCHAR2
,P_ATTRIBUTE20 IN VARCHAR2
,P_PERIOD_OF_INCAPACITY_ID IN NUMBER
,P_SSP1_ISSUED IN VARCHAR2
,P_MATERNITY_ID IN NUMBER
,P_SICKNESS_START_DATE IN DATE
,P_SICKNESS_END_DATE IN DATE
,P_PREGNANCY_RELATED_ILLNESS IN VARCHAR2
,P_REASON_FOR_NOTIFICATION_DELA IN VARCHAR2
,P_ACCEPT_LATE_NOTIFICATION_FLA IN VARCHAR2
,P_LINKED_ABSENCE_ID IN NUMBER
,P_BATCH_ID IN NUMBER
,P_CREATE_ELEMENT_ENTRY IN BOOLEAN
,P_ABS_INFORMATION_CATEGORY IN VARCHAR2
P_ABS_INFORMATION1 IN VARCHAR2,
P_ABS_INFORMATION1 IN VARCHAR2,
P_ABS_INFORMATION2 IN VARCHAR2,
P_ABS_INFORMATION3 IN VARCHAR2,
P_ABS_INFORMATION4 IN VARCHAR2,
P_ABS_INFORMATION5 IN VARCHAR2,
P_ABS_INFORMATION6 IN VARCHAR2,
P_ABS_INFORMATION7 IN VARCHAR2,
P_ABS_INFORMATION8 IN VARCHAR2,
P_ABS_INFORMATION9 IN VARCHAR2,
P_ABS_INFORMATION10 IN VARCHAR2,
P_ABS_INFORMATION11 IN VARCHAR2,
P_ABS_INFORMATION12 IN VARCHAR2,
P_ABS_INFORMATION13 IN VARCHAR2,
P_ABS_INFORMATION14 IN VARCHAR2,
P_ABS_INFORMATION15 IN VARCHAR2,
P_ABS_INFORMATION16 IN VARCHAR2,
P_ABS_INFORMATION17 IN VARCHAR2,
P_ABS_INFORMATION18 IN VARCHAR2,
P_ABS_INFORMATION19 IN VARCHAR2,
P_ABS_INFORMATION20 IN VARCHAR2,
P_ABS_INFORMATION21 IN VARCHAR2,
P_ABS_INFORMATION22 IN VARCHAR2,
P_ABS_INFORMATION23 IN VARCHAR2,
P_ABS_INFORMATION24 IN VARCHAR2,
P_ABS_INFORMATION25 IN VARCHAR2,
P_ABS_INFORMATION26 IN VARCHAR2,
P_ABS_INFORMATION27 IN VARCHAR2,
P_ABS_INFORMATION28 IN VARCHAR2,
P_ABS_INFORMATION29 IN VARCHAR2,
P_ABS_INFORMATION30 IN VARCHAR2,
P_ABSENCE_CASE_ID IN NUMBER
)
IS
L_ABSENCE_TYPE VARCHAR2 (500) := NULL;
L_ASSIGNMENT_ID NUMBER;
L_ABSENCE_START_DATE DATE := NVL (P_DATE_START, P_DATE_PROJECTED_START);
L_ABSENCE_END_DATE DATE := NVL (P_DATE_END, P_DATE_PROJECTED_END);
L_ABSENCE_FUTURE_ST_DATE DATE;
L_ABSENCE_FUTURE_END_DATE DATE;
BEGIN
SELECT NAME
INTO L_ABSENCE_TYPE
FROM PER_ABSENCE_ATTENDANCE_TYPES
WHERE ABSENCE_ATTENDANCE_TYPE_ID = P_ABSENCE_ATTENDANCE_TYPE_ID
AND BUSINESS_GROUP_ID = P_BUSINESS_GROUP_ID;
IF UPPER(TRIM(L_ABSENCE_TYPE)) = ‘ANNUAL LEAVE’ THEN
IF L_ABSENCE_END_DATE – L_ABSENCE_START_DATE > 30 THEN
HR_UTILITY.SET_MESSAGE (800, ‘LSG_ANN_LEAVE_GREATER_THAN_30’);
HR_UTILITY.RAISE_ERROR;
END IF;
END IF;
END
END LSG_CREATE_ABS_VAL_P;
END LSG_USERHOOK_PKG;
Back to top
3. Register your procedure with one or more specific user hooks.
We shall use the API_HOOK_ID identified in Step 1 in the parameter p_api_hook_id. Through this API, custom logic will be registered against user hook.
DECLARE
L_API_HOOK_ID NUMBER:= 3840
L_API_HOOK_CALL_ID NUMBER;
L_OBJECT_VERSION_NUMBER NUMBER;
L_SEQUENCE NUMBER;
BEGIN
SELECT HR_API_HOOKS_S.NEXTVAL
INTO L_SEQUENCE
FROM DUAL;
HR_API_HOOK_CALL_API.CREATE_API_HOOK_CALL
(P_VALIDATE => FALSE,
P_EFFECTIVE_DATE => TO_DATE(’01-JAN-1952′,’DD-MON-YYYY’),
P_API_HOOK_ID =>L_API_HOOK_ID NUMBER,
P_API_HOOK_CALL_TYPE => ‘PP’,
P_SEQUENCE => L_SEQUENCE,
P_ENABLED_FLAG => ‘Y’,
P_CALL_PACKAGE => ‘LSG_USERHOOK_PKG’, — CUSTOM PACKAGE
P_CALL_PROCEDURE => ‘LSG_CREATE_ABS_VAL_P’, — CUSTOM PROCEDURE
P_API_HOOK_CALL_ID => L_API_HOOK_CALL_ID,
P_OBJECT_VERSION_NUMBER => L_OBJECT_VERSION_NUMBER);
DBMS_OUTPUT.PUT_LINE(‘L_API_HOOK_CALL_ID ‘|| L_API_HOOK_CALL_ID);
END ;
After this step, you shall be able to see the reference of your custom package/ procedure in table HR_API_HOOK_CALLS. You can check it by using following query
SELECT *
FROM HR_API_HOOK_CALLS
WHERE api_hook_id = 3840;
Back to top
4. Run the pre-processor program
Run pre-processor script hrahkone.sql with module name as parameter (PER_TOP/admin/sql/hrahkone.sql).It compile API hook. After running this your APIhook Package should have custom procedure call.
or
Alternately you can use the following API to run the pre-processor
declare
l_api_module_id number := 1731; –Value 1731 is derived from Step 1 above using following query
begin
hr_api_user_hooks_utility.create_hooks_one_module (l_api_module_id);
dbms_output.put_line(‘Success’);
exception when others then
dbms_output.put_line(‘Exception : ‘||SQLERRM);
end;
At this level, your user hook is implemented and should work as per your requriement.
If you change your custom package body, you dont need to run the pre-processor again but if you change the procedure signature, you will need to run the pre-processory again,
Back to top
Delete custom code from APIuser Hook
Get Hook Call ID and Object Version_number
SELECT api_hook_call_id,object_version_number
FROM HR_API_HOOK_CALLS
WHERE call_package = ‘LSG_USERHOOK_PKG’
AND call_procedure = UPPER(‘LSG_CREATE_ABS_VAL_P’)
BEGIN
Hr_Api_Hook_Call_Api.delete_api_hook_call ( p_validate => FALSE,
p_api_hook_call_id => 12345,
p_object_version_number =>2
);
DBMS_OUTPUT.PUT_LINE(‘deleted Successfully’);
END;
