Escolar Documentos
Profissional Documentos
Cultura Documentos
Understanding and Using Application Program Interface (API) User Hooks in Oracle HRMS
Applies to: Oracle Human Resources Information in this document applies to any platform.
Goal To explain how to add extra logic to the Business APIs using User Hooks. This document explains the advantages and disadvantages of User Hooks, and how to implement them. For further reading, see the API User Hooks section in the Oracle Human Resources Management Systems Implementation Guide Solution
Contents
1. General Introduction ....................................................................................................................... 4 2. Advantages ...................................................................................................................................... 5 3. Disadvantages ................................................................................................................................. 6 4. Implementing User Hooks ............................................................................................................... 7 5. Available User Hooks....................................................................................................................... 8 5.1 Business Process Hooks............................................................................................................. 9 5.2 Row Handler Hooks ................................................................................................................. 10 5.3 Available Data Values .............................................................................................................. 11 6. Using User Hooks .......................................................................................................................... 12 6.1 Writing the custom PL/SQL procedure ................................................................................... 12 6.2 Registering the User Hook....................................................................................................... 13 6.3 Running the Pre-Processor ...................................................................................................... 15 6.4 Running the Custom Procedure .............................................................................................. 18 7. Tips on resolving Invalid Hook Packages ....................................................................................... 20 8. References ..................................................................................................................................... 23
1. General Introduction
API User Hooks allow users to extend the business logic of the standard business rules that are executed by APIs. This is done by allowing custom procedures to be called at specific points in the standard APIs. For instance, a user may want to implement User Hooks for one of the following reasons: To extend the validation of data beyond what the standard system provides. To maintain data held in extra customer specific tables (not part of Oracle Applications) as it is entered. To send alerts when particular events happen within Oracle Human Resources Management System (HRMS).
User Hooks offer similar functionality to the Custom Library, but at the database end rather than the front end. The table HR_API_HOOKS contains all the hooks available for each API module listed in the HR_API_MODULES table.
2. Advantages
User Hooks allow extra business logic to be inserted in exactly the right place in the application without needing to bespoke any of the standard APIs. Upgrades are no problem as the hooks will be regenerated during the upgrade process. However, Oracle reserves the right to change the HR schema at any time, which may necessitate modifications to customized PL/SQL procedures. The main advantages of hooks over custom library are that they only need to be implemented in one place whereas custom library modifications could conceivably have to be made on several clients. They are also immediately available to any interface that calls the API. For example, Forms, Self Service, Data Pump, etc.
3. Disadvantages
A customized procedure called by a User Hook will only work if the API that the call has been added to is executed. It sounds obvious. However, at the time of writing there are still a large number of forms that don't call APIs. The Enter Person Information form is one of them. Therefore, any hook added to the Create_Employee API will not be executed from this form. It is policy to eventually convert all existing forms to call APIs but this will not be a short term process. Unfortunately, there is no list available which indicates which forms call APIs and which do not. The only certainty is that all new forms will call APIs. A sensible approach to any implementation of configuration logic, therefore, if required to be executed by a standard form, is for the user to use a hook if the form calls a supported API, and custom library if not.
MODULE_NAME -----------------------------CREATE_GB_APPLICANT CREATE_GB_EMPLOYEE CREATE_GB_PERSONAL_PAY_METHOD CREATE_GB_PERSON_ADDRESS CREATE_GB_SECONDARY_EMP_ASG CREATE_US_APPLICANT CREATE_US_EMPLOYEE CREATE_US_PERSONAL_PAY_METHOD CREATE_US_PERSON_ADDRESS CREATE_US_SECONDARY_EMP_ASG UPDATE_GB_EMP_ASG UPDATE_GB_PERSON UPDATE_GB_PERSONAL_PAY_METHOD UPDATE_GB_PERSON_ADDRESS UPDATE_US_EMP_ASG UPDATE_US_PERSON UPDATE_US_PERSONAL_PAY_METHOD UPDATE_US_PERSON_ADDRESS
User Hooks are also not provided for utility type APIs such as CREATE_MESSAGE_LINE.
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.
There are 5 different types of User Hook. Two for Business Process APIs (Before Process and After Process), and 3 more for Row Handler APIs (After Insert, After Update and After Delete).
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. 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='CREATE_EMPLOYEE' and ahm.api_module_type = 'BP' and ahk.api_hook_type = 'AP' and ahk.api_module_id=ahm.api_module_id;
HOOK_PACKAGE --------------------HR_EMPLOYEE_BK1
HOOK_PROCEDURE --------------------------CREATE_EMPLOYEE_A
The 3 types of Row Handler hook available are: After Insert After Update After Delete 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
SQL> /
HOOK_PROCEDURE -------------------------AFTER_INSERT
*** Note: The module_name should be PER_ALL_PEOPLE_F, but on early versions of R11 PER_PEOPLE_F was erroneously used.
10
Old values are not available on Before Process, After Process and After Insert hooks. A complete list of parameters available for each hook can be obtained by running the script $PER_TOP/admin/sql/hrahkpar.sql.
11
SQL> DESC HR_API_HOOK_CALLS Name ------------------------------API_HOOK_CALL_ID API_HOOK_ID API_HOOK_CALL_TYPE LEGISLATION_CODE SEQUENCE ENABLED_FLAG CALL_PACKAGE CALL_PROCEDURE PRE_PROCESSOR_DATE ENCODED_ERROR STATUS OBJECT_VERSION_NUMBER LAST_UPDATE_DATE LAST_UPDATED_BY LAST_UPDATE_LOGIN CREATED_BY CREATION_DATE Null? -------NOT NULL NOT NULL NOT NULL NOT NULL NOT NULL Type ---NUMBER(15) NUMBER(15) VARCHAR2(30) VARCHAR2(30) NUMBER(15) VARCHAR2(30) VARCHAR2(30) VARCHAR2(30) DATE VARCHAR2(2000) VARCHAR2(30) NUMBER(15) DATE NUMBER(15) NUMBER(15) NUMBER(15) DATE
NOT NULL
There are 3 special procedures that maintain data in this table. These are . hr_api_hook_call_api.create_api_hook_call . hr_api_hook_call_api.update_api_hook_call . hr_api_hook_call_api.delete_api_hook_call Fig 2 shows how to register the user hook. 13
Fig 2. 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); end;
a. See section 5.1 to get api_hook_id. 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.
Fig 3 shows a call to delete a link. Fig 3. 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); end;
14
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.
,P_LAST_NAME in VARCHAR2 ,P_SEX in VARCHAR2 ,P_PERSON_TYPE_ID in NUMBER ,P_PER_COMMENTS in VARCHAR2 ,P_DATE_EMPLOYEE_DATA_VERIFIED in DATE ,P_DATE_OF_BIRTH in DATE ,P_EMAIL_ADDRESS in VARCHAR2 ,P_EMPLOYEE_NUMBER in VARCHAR2 ,P_EXPENSE_CHECK_SEND_TO_ADDRES in VARCHAR2 ,P_FIRST_NAME in VARCHAR2 ,P_KNOWN_AS in VARCHAR2 ,P_MARITAL_STATUS in VARCHAR2 ,P_MIDDLE_NAMES in VARCHAR2 ,P_NATIONALITY in VARCHAR2 ,P_NATIONAL_IDENTIFIER in VARCHAR2 ,P_PREVIOUS_LAST_NAME in VARCHAR2 ,P_REGISTERED_DISABLED_FLAG in VARCHAR2 ,P_TITLE in VARCHAR2 ,P_VENDOR_ID in NUMBER ,P_WORK_TELEPHONE in VARCHAR2 ,P_ATTRIBUTE_CATEGORY in VARCHAR2 ,P_ATTRIBUTE1 in VARCHAR2 ,P_ATTRIBUTE2 in VARCHAR2 ... ... ,P_ATTRIBUTE29 in VARCHAR2 ,P_ATTRIBUTE30 in VARCHAR2 ,P_PER_INFORMATION_CATEGORY in VARCHAR2 ,P_PER_INFORMATION1 in VARCHAR2 ,P_PER_INFORMATION2 in VARCHAR2 ... ... ,P_PER_INFORMATION29 in VARCHAR2 ,P_PER_INFORMATION30 in VARCHAR2 ,P_BACKGROUND_CHECK_STATUS in VARCHAR2 ,P_BACKGROUND_DATE_CHECK in DATE ,P_BLOOD_TYPE in VARCHAR2 ,P_CORRESPONDENCE_LANGUAGE in VARCHAR2 ,P_FAST_PATH_EMPLOYEE in VARCHAR2 ,P_FTE_CAPACITY in NUMBER ,P_HONORS in VARCHAR2 ,P_INTERNAL_LOCATION in VARCHAR2 ,P_LAST_MEDICAL_TEST_BY in VARCHAR2 ,P_LAST_MEDICAL_TEST_DATE in DATE ,P_MAILSTOP in VARCHAR2 ,P_OFFICE_NUMBER in VARCHAR2 ,P_ON_MILITARY_SERVICE in VARCHAR2 ,P_PRE_NAME_ADJUNCT in VARCHAR2 16
,P_PROJECTED_START_DATE in DATE ,P_RESUME_EXISTS in VARCHAR2 ,P_RESUME_LAST_UPDATED in DATE ,P_SECOND_PASSPORT_EXISTS in VARCHAR2 ,P_STUDENT_STATUS in VARCHAR2 ,P_WORK_SCHEDULE in VARCHAR2 ,P_SUFFIX in VARCHAR2 ,P_PERSON_ID in NUMBER ,P_ASSIGNMENT_ID in NUMBER ,P_PER_OBJECT_VERSION_NUMBER in NUMBER ,P_ASG_OBJECT_VERSION_NUMBER in NUMBER ,P_PER_EFFECTIVE_START_DATE in DATE ,P_PER_EFFECTIVE_END_DATE in DATE ,P_FULL_NAME in VARCHAR2 ,P_PER_COMMENT_ID in NUMBER ,P_ASSIGNMENT_SEQUENCE in NUMBER ,P_ASSIGNMENT_NUMBER in VARCHAR2 ,P_NAME_COMBINATION_WARNING in BOOLEAN ,P_ASSIGN_PAYROLL_WARNING in BOOLEAN )is l_commit_unit_number number; l_legislation_code varchar2(30); begin hr_utility.set_location('Entering: HR_EMPLOYEE_BK1.CREATE_EMPLOYEE_A', 10); l_commit_unit_number := hr_api.return_commit_unit; if hr_api.call_cus_hooks then SCOOP_NATIONALITY_CHECK.POLISH_NAME_CHECK (P_LAST_NAME => P_LAST_NAME ,P_NATIONALITY => P_NATIONALITY ); end if; hr_api.validate_commit_unit(l_commit_unit_number, 'CREATE_EMPLOYEE', 'AP'); hr_utility.set_location(' Leaving: HR_EMPLOYEE_BK1.CREATE_EMPLOYEE_A', 20); end CREATE_EMPLOYEE_A;
If you want to disable a custom package procedure, then the API hr_api_hook_call_api.update_api_hook_call must be executed to set the p_enabled_flag to N. Afterwards the pre-processor must be run to recreate the hook package body. To re-enable,set the p_enabled_flag back to Y and re-run pre-processor. Similarly if you permanently delete the definition using the delete API described in section 6.2, you must run the pre-processor afterwards to remove the hard coded call (see Fig 4) from the hook package body.
17
If the Pre-Processor errors, it will set the status on HR_API_HOOK_CALLS to I for Invalid. Status will be V for Valid if successful. If it errors the message is written to the ENCODED_ERROR column. This can be read using the following SQL: declare l_encoded_error varchar2(2000); l_user_read_text varchar2(2000); begin Substitute ??? with the value held in the HR_API_HOOK_CALLS.ENCODED_ERROR column. l_encoded_error := ???; fnd_message.set_encoded(encoded_error); l_user_read_text := fnd_message.get; end;
,p_first_name => 'Ania' ,p_nationality => 'BEL' ,p_person_id => l_person_id ,p_assignment_id => l_assignment_id ,p_per_object_version_number => l_per_object_version_number ,p_asg_object_version_number => l_asg_object_version_number ,p_per_effective_start_date => l_per_effective_start_date ,p_per_effective_end_date => l_per_effective_end_date ,p_full_name => l_full_name ,p_per_comment_id => l_per_comment_id ,p_assignment_sequence => l_assignment_sequence ,p_assignment_number => l_assignment_number ,p_name_combination_warning => l_name_combination_warning ,p_assign_payroll_warning => l_assign_payroll_warning ); end;
Fig 6. declare * ERROR at line 1: ORA-20999: Nationality must be Polish ORA-06512: at "APPS.SCOOP_NATIONALITY_CHECK", line 11 ORA-06512: at "APPS.HR_EMPLOYEE_BK1", line 131 ORA-06512: at "APPS.HR_EMPLOYEE_API", line 504 ORA-06512: at line 21 If the error is raised in a form then the following error displays. The detail displays when clicking on History. FRM-40735: trigger raised unhandled exception ORA-20999
Detecting whether a reported error is raised by a custom procedure or not may be a challenging exercise for a support analyst. However, that is usually the case with any bespoke code. The clues to look for are a. Familiarity with standard error messages. Is this a standard HRMS message?
19
b. The error code may give a clue. Example; if a particular range has been used to raise application errors in the custom procedure. In this case ORA-20999. Usually the range 20000 - 20999 are reserved for raising errors from triggers and packaged procedures. c. The package reporting the error is the real give away. HR_EMPLOYEE_BK1 is a hook procedure.
8/11 PLS-00323: subprogram or cursor 'CREATE_SECONDARY_EMP_ASG_B' is declared in a package specification and must be defined in the package body 179/11 PLS-00323: subprogram or cursor 'CREATE_SECONDARY_EMP_ASG_A' is declared in a package specification and must be defined in the package body For this type of error, find the file that delivers Hook Package HR_ASSIGNMENT_BK1 by cd $PER_TOP/patch/115/sql grep -i 'HR_ASSIGNMENT_BK1' *.pkh then reapply the package header and body in sqlplus sqlplus apps/apps@$PER_TOP/patch/115/sql/peasgapi.pkh sqlplus apps/apps@$PER_TOP/patch/115/sql/peasgapi.pkb then find the script that delivers the hook seed data 20
grep -i 'HR_ASSIGNMENT_BK1' *.sql and run it in sqlplus sqlplus apps/apps@$PER_TOP/patch/115/sql/peasgasd.sql Recompile APPS schema. Then you can run a script to identify invalid objects
and/or rerun $PER_TOP/patch/115/sql/hrahkall.sql to see if it has been removed from the error report
Example 2 in the report you may see an error like this Module Name: UPDATE_ORG_INFORMATION Module Type: Business Process API Hook Package: HR_ORGANIZATION_BK2 172/1 PLS-00201: identifier 'INVALID_SEE_COMMENT_IN_SOURCE' must be declared 172/1 PL/SQL: Statement ignored Hook: Before Process The legislation function can only be a function. It cannot be a procedure. This API module will not execute until this problem has been resolved. For this error the problem lies in a function called from the Hook Package, HR_ORGANIZATION_BK2. Examine the package and see where it is calling the legislation function from. In this case it is
21
So reapply the files that delivers HR_ORI_BUS, followed by the script that delivers the hook seed data for the hook package (see example 1)
sqlplus apps/apps@$PER_TOP/patch/115/sql/hrorgasd.sql
If recompiling has not resolved the problem, a code fix may be required, so check the knowledge repository for known issues and contact Oracle Support as required.
22
8. References
Note Metalink ID 73170.1
23