Vision Custom Lib

HRMS Release 11 Vision Custom Library Examples

The following details work carried out by the Release 11 HRMS Vision team to implement Custom Library examples onthe Release 11 vision database. This document is not meant to be an instructor manual for those presenting this feature.It is meant to be a more technically biast description of exactly what was done to achieve the changes to the visionenvironment. It also gives a brief description of the scenarios implemented.

The format of this document is as follows:

• Objectives• Overview of the Custom Library Application Server Architecture• Details of scenarios implemented• Selling points Appendices • Appendix 1 - Guidelines For The Addition Of User Defined Business Rules Within The Oracle Applications White Paper - Andrew McGhee, April 1998• Appendix 2 - Copy of CUSTOM.pll• Appendix 3 - Copy of HRCUSTOM.pll• Appendix 4 - Copy of HRCUST1.pll• Appendix 5 - Copy of HRCUST2.pll• Appendix 6 - Copy of Server Side Custom Library Code ( server_cl_code.sql )

Objectives

During the setting up of the Release 11 vision database, it was decided to add Custom Library scenarios to show peoplewhat a powerful feature it is when used in conjunction with the Oracle HRMS Application. At the same it was decided toinclude at least one scenario that made use of the Release 11 Formula PL/Sql function.

Overview Of The Custom Library Application Server Architecture

The Custom Library is a feature that is available from within any of the Oracle Applications, it is not Oracle HRMSspecific. This feature first appeared in the Production 13 Smart Client release of the Oracle Applications.

Since there is only a single library, one has to give careful consideration to the design of any code they decide to putwithin the library. As the library is nothing more than a Forms library, all restrictions and limitations that exists in anystandard Forms library also apply to the Custom library.

The Custom Library is actually a file called CUSTOM.pll and CSUTOM.plx. The ‘.plx’ extension is a compiled versionof the ‘.pll’ file. These files reside on the Application server in the $AU_TOP/resource directory. Be aware that if boththe ‘.pll’ and ‘.plx’ versions of the file exist in the same directory then Oracle Forms will use the ‘.pll’ version of thefile.

For the purpose of the vision environment set up, a number of additional HRMS specific libraries were created. This wasto show how one might go about splitting additional Form Custom Library logic between multiple libraries ( based onForm name ).

The Custom Library can be switched on and off dynamically by the user by selecting the Help.. Tools.. Custom Code..Off option from the menu bar. You can prevent users from being able to switch off the Custom Library by setting aprofile option ( that I can’t remember at the time of going to press ).

Further details about the Release 11 Custom Library can be found in the Release 11 Applications Documentation “Zoomand Customizing Oracle Applications” (http://www-apps.us.oracle.com/doclib/11.0/comus/us/index.htm ).

Details Of Scenarios Implemented

All of the scenarios implemented required code to be created in a Forms library and / or a newly created server sideprocedure. Both the libraries and procedures have been heavily documented and are attached to this document asappendices

The following scenarios were implemented:

Scenario 1 - Person & ‘Mega’ Person Form ( PERWSEPI, PERWSHRG )

When entering the Person form, the user is prompted as to whether they would like a pre-selected list of ‘required’ fieldsto be highlighted. The selected fields are:

Last Name Person Type GenderEmployee Number Social Security Number Date Of Birth

In addition to the above fields, the ‘Ethnic Origin’ field is one of the selected fields if you are running in a U.S.legislation.The user has to select ‘Yes’, ‘No’, or ‘Cancel’. If they select ‘Yes’ then the fore mentioned fields are highlighted in blue.

HRCUSTOM Library

CUSTOM Library

HRCUST2 Library HRCUST1 Library

R11 Vision HRMS Custom Library Architecture

PERWSEPY, PAYWSMEE,PERWSEAD

PERWSHRG, PERWSEPI,PERWSEMA


This scenario is associated with scenario 1. When saving changes in the above forms, and the employee type is‘Employee’, a check is made to see whether the user selected to highlight required fields ( scenario 1 ). If the user choseto highlight the fields then they are only able to save their changes if all of the required fields have been entered. If theyhaven’t entered all of the fields then a suitable message is displayed. The message is different depending on the currentlegislation. If the message is displayed then the record is prevented from being able to commit.


When entering the Person form, the user is prompted as to whether they would like to hide the “Mail To” field.

The user has to select ‘Yes’, ‘No’, or ‘Cancel’. If they select ‘Yes’ then the Mail To field is removed from the form.

NOTE: When removing the Mail To field, the test ‘Mail To’ still remains. This is because the text is part of the boilerplate for the form and it isn’t currently possible to dynamically remove boiler plate text. Apparently in Forms 5 you will/ are able to dynamically remove boiler plate text.

Scenario 4 - Salary Administration Form ( PERWSEPY )

When saving salary proposal details, extra validation is performed to check whether the proposal amount falls withinmarket salary minimum and maximum values associated with the job the person is assigned to. If the amount is outsideof the range then a warning message is displayed ( but the user is allowed to commit the changes ).

Two segments, market salary minimum and market salary maximum, were created on the ‘Additional Job Details’flexfield. These segments are used to compare the entered proposal amount against.

A server side procedure was created to retrieve these values from the jobs table.

Scenario 5 - Element Entry Form ( PAYWSMEE )

A new element was created, Earnings Potential’ with two input values with the following definitions

Sequence Input Name User Enterable 1 Current Earnings Yes 2 Earnings Potential No

As well as creating the above element, a new formula, CL_EARN_POTENTIAL, was created. This formula basicallydoes the following:

Accept an input; current earnings

If the person doesn’t have a date of birth entered thenearnings potential = 0earnings message = ‘Persons age not recorded. Unable to work out future earnings potential’

If the persons age is >= 30 thenearnings potential = current earnings * 4.5earnings message = ‘Earnings potential is 4.5 times Current Earnings’

If the persons age is < 30 thenearnings potential = current earnings * 1.5

earnings message = ‘Earnings potential is 1.5 times Current Earnings’

Having entered the current earnings input value, the user is prevented from entering the earnings potential segment. Onsaving the change, a call is made to a server side procedure that execute the CL_EARN_POTENTIAL formula. Theformula returns two values; earnings potential and earnings message. The earnings potential returned value us used toupdate the earnings potential input segment on the element. The earnings message is displayed to the user.

This scenario demonstrates a number of things:

• How the Custom Library can be used to update non-enterable fields• How the Custom Library can call a server side procedure that then executes a Formula PL/Sql program• How Formulas can be used to store business rules

Having entered the element for a person, it looks really good if you then edit the formula to change the message /calculation logic and then update the saved element to show the new message / calculation being performed !!! On-Lineupdating of business rules !!!

NOTE: The above was set up within the US HRMS Manager. The Earnings Potential element was set up within boththe US and UK Vision HRMS business group. This means that when showing this within the UK business group, youhave to switch responsibility to the US business group to update the formula.

Scenario 6 - Absence Form ( PERWSEAD )

When entering ‘Family Leave’ absences for an individual, the FMLA 12 month rolling average hourly and weeklyamounts are calculated. Two new segments were created on the Additional Absence Details descriptive flexfield to holdthe rolling totals:

Accumulated DaysAccumulated Weeks

The rolling 12 month period is from the ( actual absence end date minus 12 months ) to the actual absence end date.

It is assumed that there are 8 hours in a day and 40 hours in a week. The current scenario doesn’t do any checks aboutcalendars and weekends etc.

A server side procedure was created to do the accumulation.

Scenario 7 - Modulus 11 Check Digit ** NOT IMPLEMENTED IN CUSTOM LIBRARY

In the server side package that was created, vision_cl_code, there is a procedure called check_digit. This routine acceptsa number as input and calculates the Modulus 11 check digit value.

This routine may be useful to show how it is possible to perform check digit calculations when entering EmployeeNumbers.

Scenario 8 - Euro Currency Conversion ** NOT IMPLEMENTED IN CUSTOM LIBRARY

In the server side package that was created, vision_cl_code, there is a procedure called euro_conversion. This routineretrieves the EURO exchange rate value from the HR Exchange Rates table. Specific details of pre-requisite setuprequirements can be found in the source code for the server side procedure ( appendix 6 ).

Selling Points

The Custom Library is a very strong feature in its own right but when combined it with Formula PL/Sql and API UserHooks, we have a VERY powerful business rule methodology.

Appendix 1 contains a copy of an excellent White paper, Guidelines For The Addition Of User Defined Business RulesWithin The Oracle Applications; Andrew McGhee, April 1998. This brings together these new technologies andpresents a framework of how they can be used together to provide an total business rule solution within the OracleHRMS Application.

Good luck in your use of this new technology…

The Release 11 HRMS Vision Team

Appendix 1 - Guidelines For The Addition Of User Defined Business Rules Within The Oracle Applications White Paper - Andrew McGhee, April 1998

GUIDELINES FOR THE ADDITION OF USER DEFINED BUSINESS RULES WITHIN THE ORACLEAPPLICATIONS

Andrew McGheeHRMS Product Support Manager

Oracle Corporation, Bracknell, UK

Summary

It has become evident in recent years that the nature and structure of the Information Technology ( IT ) departmentwithin large organizations is changing. This change is being driven from the highest levels of the organization and isfundamentally affecting the organization and its culture. I am referring to the way in which IT is perceived from withinthe organization and the role it plays to achieve overall corporate success. The IT department may once have beenviewed as an independent function within the organization but this is no longer the case. CIO’s are realising that theirstaff need to recognise that the needs of the business must drive technology decisions. Cross functional team projects arebecoming common place. This typically involves players from multiple discipline ( business, technology etc ), whichenables knowledge to be harnessed to the broader objectives of the project. The business rules and requirements aretherefore taking centre stage when reviewing what applications are required to support the overall objectives and goalsof the organization. This does not however lessen the importance of choosing the right technology. Wrong decisions inthis area could be disastrous.

In the past when organizations have looked to create or replace internal business application packages, their optionswere primarily:

1. Buy an ’off the shelf’ built application and hope that it meets all or most of the needs of the organization2. Custom build the required application from start to finish yourself

Both of the above options were considered mutually exclusive and they both have their own relative advantages anddisadvantages. Off the shelf applications are ideal if the ‘100% requirement fit’ can be satisfied ( but isn’t everyorganization slightly different in some way from another ? ). Custom built applications give you everything that youwanted but the cost of internal ownership of the application ( code, support, maintenance etc ) is high. This paper looksat some well known and some not so well known tools and technologies and new features within the Oracle Applicationsthat make it possible to extend the Oracle Applications to help satisfy your unique business rule requirements within asupportable, manageable and upgradeable framework. In order to review the suitability of the tools and technologies forsatisfying business rules, we will examine exactly what is meant by the term ‘business rule’ and review how these can beimplemented using identified tools, technologies and techniques.

Scope

This paper will look at possible strategies for the addition of business rules to the Oracle Applications in a controlled,supported and upgradeable manner. We will address the following:

• What is a business rule ?• Can business rules be categorised / classified ? If so, how ?• Standard business rule coding options ( Forms, Reports, PL/Sql )• New coding options ( Custom Library, APIs )• Coding options post Release 10 ( API User Hooks, Formulas Generating PL/Sql )• Examples of implementing identified business rule categories

To get the best from a packaged solution, the package must be implemented as it was designed to be used with as littlealteration to the core package as possible. Following this policy mitigates the risks associated with the ability to upgradeand move forward with the new package, taking advantage of new features and technologies. This in turn reduces thecost of ownership over time.

This paper is not intended to be a replication of previous papers on the subject of architecturing your applicationsenvironment for the development and preservations of customisations. I may at times refer to ‘good practices’ outlined inprevious articles but hopefully, most of what this paper covers will be new to the reader.

The application software baseline used in the examples for this paper was Oracle Applications Production 16.1 SmartClient. Most of what is recommended is applicable to all of the Oracle Application Smart Client modules ( GL, PO, AP,AR etc ). However, there are some sections that are only relevant to the Oracle HRMS suite of application modules. Suchunique examples will be highlighted as required. The Human Resources ( HR ) and Payroll application will be used forthe highlighting of all examples within this paper.

What is a Business Rule ?

A business rule, for the purpose of this paper, is any rule of business that is required to be enforced by virtue ofperforming a specific business function. For example;

“For each person entered on the system, you must record the gender of the individual” or

“A person can only be promoted if they have held their current position for more than 3 years”

Oracle Applications, by their very nature and design, are very flexible and extendible. Data definitions e.g. position andgrade definitions, are user definable and can be built to suit the individual requirements of your organization. Thesedefinitions represent a ‘meta’ data definition layer of the underlying structures. Such definitions, because they are storedwithin the application as data in tables, are protected during future upgrades of the application. The applications alsoenable the definition of user specific ‘attribution’ within key and descriptive flexfields and special information types (HRMS specific ).

Can Business Rules be Categorised / Classified ? If so, How ?

During any standard functional gap analysis exercise ( using the Oracle Applications Implementation Methodology,AIM, for example ), when a new applications is being evaluated / tested for ‘degree of fit’ suitability, organizationalbusiness requirements and rules are tested / mapped on to the new software. A pre-requisite for this is that existingbusiness procedures, rules and requirements have already been identified and recorded.

Looking back at the definitions of example business rules ( above ), you will be able to identify that each example couldrepresent a different category of rule. Why, some may ask, is it necessary or good practice to spend time grouping rulesinto different categories ? The process of categorising rules will facilitate:

• The identification of duplicate and redundant rules• The estimation of effort required to implement all rules based on the numbers in each category• The recording and documentation of rules which will help on-going support and understanding of the application

by everyone involved in the project. This will also make the process of future upgrades more manageable.

When categorising business rules, the interface mechanism ( e.g. OLTP or batch processing ) to interact with theapplication is not important. What is important is that the rules relate to specific data items or processes that areimportant to the business.

The following is an example of a business rule categorisation chart that I have used. For each rule category, I haveattempted to give an example of an appropriate business rule.

Business Rule Categories

Process Flow Rules

Calculation Rules

Data Operation / Event Rules

Static Data Rules

Single Data Item Attribute Rules

Entity Rules

Multi Data Item Dependency Rules

Update Rule

Delete Rule

Create Rule

Access Rules

Relationship Rules

Entitlement Rules

Requirement Rules

Logic Attribute Rules

Required

Domain

Format

Data Item Specific Validation

Data Item Required or Not

Data Item Allowable Values

Data Item Size and Construct

The start date of an employee cannot fall on a weekend

When entering a person, you must enter their nationality

When creating a new employee, notify the employees newmanager of joining / starting details

Rules that involve numeric algorithms to compute results e.g.calculate monthly salary from yearly salary value; calculateabsence days to date when entering new absence details for anemployee

When hiring an applicant, the approving manager mustforward on the request to his manager to approve the hire.Only when this is complete, can the applicant be formallyhired.

Application details made to the organization within the past twoyears can’t be deleted from the system

Employee salaries can only be increased by amounts as definedby the current organization grading structure

The personnel administrator for the finance department is onlyable to view employees who work within that department

A person must only have one current salary element at any onetime

Only directors are entitled to company stock options

Each employee must have a home address record

A persons previous last name cannot be the same as thepersons current last name

Item ‘x’ can only have a value if item ‘y’ is entered

Organization unique absence types must be available forspecified data item values

Employee phone numbers data items must be able to storecountry dialing codes as well as the number

These rules are hard to classify and could meandifferent things to different people

2.3

2.2

2.1

1.3.4

1.3.3

1.3.2

1.3.1

1.3

1.2

1.1.4

1.1.3

1.1.2

1.1.1

1.1

4

3

2

1

Some individuals may be more comfortable with categorising entity type rules in terms of data operation or event e.g.create / update / delete. Be aware that this would require many entity rules to be listed more than once ( as create rulesoften need to be checked during update as well ).

The above groupings are not meant to be a finite definition of categories. As shown with the definition of entity rules,certain individuals may be more comfortable using data operation / event type groupings instead.

I have found the above categories in the past to be a good starting point for mapping discussions. Later in this paper wewill review these categories and highlight what tools, technologies and techniques are appropriate for implementingeach of the categories.

Well Known Customization Coding Options

One of the advantages of having to customize / extend Oracle Applications is that there are industry leadingdevelopment tools available to assist you in such a task. Tools include:

Oracle Designer 2000 Oracle Developer 2000 Oracle Discoverer 3.0PL/Sql SQL*Plus Pro*C

Many previous White Papers have been presented on the subject of development tools and their use in conjunction withthe Oracle Applications. I will not repeat what has already been said. I would however refer you a White Paper entitled“Architecturing Your Applications Environment for the Development and Preservation of Customizations”, PaulaKodjou, Oracle Corporation. The paper was presented at the OAUG Spring 1996 conference in Orlando, Florida. Thispaper builds on the Oracle Application Development standards to present strategies for creating environments thatsupport customizations.

All of the above tools are used by the Oracle Applications development teams to actually create the various applicationsystem modules. It therefore goes without saying that these tools would be preferred choices when deciding what to useto extend the applications.

Not So Well Known Customization Options

As everybody well knows, the Oracle Applications are constantly evolving in the areas of both functionality and featuresand their use of leading edge technology. This means that keeping up to date with new features could be described as anart in itself. From Production 13 of the Oracle Applications Smart Client release, a new feature was introduced to theapplications called the ‘Custom Library’.

The custom library is a facility that enables you to augment and extend the Oracle Applications without modification ofOracle Application code. The custom library can be used for defining ‘zooms’ ( a mechanism to ‘jump’ to forms fromother forms ) and for enforcing business rules. Some good definitions of the custom library are:

“A mechanism that allows extension of Oracle Applications without modification of Oracle Application code” or

“An Oracle Forms PL/Sql library that allows you to take full advantage of all of the capabilities of the Developer2000 suite of products and integrate your code directly with Oracle Applications”

or“A supported, upgradeable, user definable, partitioned code repository for custom code”

The custom library is a reserved area for user defined extra validation and changes that preserve the base OracleApplication form on upgrade and allow the custom changes to be easily de-coupled when investigating bugs so that thebase Oracle Application form can be supported. As you may have already gathered, the custom library is only associatedwith the application On-Line interface i.e. Forms. It is not suitable for batch type interfaces.

The custom library works in the following way; the Oracle Application forms send ‘events’ to the custom library. Userdefined custom code can then take effect based on these events. This unique facility is provided for the exclusive use of

Oracle Application customers. The Oracle Application products do not supply any predefined logic in the custom libraryother than the procedure shells.

It is important to be aware that you must not modify any component of an Oracle Applications module ( either directlyor through the custom library ) without a thorough understanding of the processing logic and underlying databasestructure for the component.

Appendix 1 details a list of things that I wish that I had known and learnt when using the custom library within aProduction 16.1 Smart Client environment.

Custom Library Architecture

Custom Library Structure

Standard event triggers in the application forms call APPCORE routines that in turn call the custom library. Otherlibraries exist that are called in the same manner as the custom library but these libraries are for application internal useonly and changes to them are ‘NOT’ supported.

Release 10 Custom Library Support Event Points

The custom library receives two different kinds of event call; generic and product specific. Generic events are commonfor all Forms in Oracle Applications. Product specific events are reserved for future use by the applications and arespecific to individual applications. Generic custom library events in Release 10 Smart Client include:

WHEN-NEW-FORM-INSTANCE WHEN-NEW-BLOCK-INSTANCE EXPORT WHEN-NEW-RECORD-INSTANCE WHEN-NEW-ITEM-INSTANCE WHEN-VALIDATE-RECORD ZOOM

Libraries contain reusable client side code. They enforce coding standards by allowing the same code to be used by allforms to enforce specific validation, navigation and cosmetic behaviours. Libraries allow code to be written once andused by multiple forms. Additionally, because the executables attach at run time, they facilitate the development andmaintenance without being invasive to a form.

In basic terms, the custom library lets you change properties, functionality and operation of a form as if you wereactually changing the source code of the form. Of course you cannot do in a library everything that it is possible to dowithin a form but you may be surprised by just how much can be done.

Some examples of the types of things that I’ve been able to do to date with the custom library using the above eventpoints include:

• Changing form field properties e.g. hiding form fields• Adding additional field validation and cross field validation• Changing a default LOV or ‘Default Where’ clause• Automatically populate fields based on some form of server side computation• Write audit logs directly to file

ApplicationForm

APPCORELibrary

CUSTOMLibrary

Contains packages and procedures that are required for all forms tosupport the menu, toolbar and other required standard behaviours

• Call new forms that interact with core forms

In addition to the above, the custom library can be used for:

• Manipulating conditionally required fields• Manipulating mutually exclusive fields• Setting of default values• Setting of inter field calculation between added fields• General processing at event points

Release 11 HRMS Custom Library Supported Events

This section is only applicable to the Oracle HRMS suite of applications.

When working with a very large public sector organization, who had many thousands of so called business rules, it wasevident that the standard custom library event points were not sufficient in order to be able to satisfy all of their businessrule requirements. As a result, the HRMS application development group identified additional event points that would beuseful to both HRMS customers and internal HRMS localization and verticalization teams. The identified event pointswere:

WHEN-CREATE-RECORD POST-QUERY KEY-DELREC PRE-UPDATE PRE-INSERT PRE-DELETE POST-UPDATE POST-INSERT POST-DELETE POST-FORMS-COMMIT SPECIALn NAVIGATE WHEN-FORM-NAVIGATE WHEN-BUTTON-PRESSED

These event points were added to a subset of Release 11 Oracle HRMS Application forms. Forms without these newevent points will be updated at some point in the future.

The addition of these new event points to all HRMS Application forms will give users of the application much morescope and facilities to extend the functionality of the base application. As we have already seen, these Custom Librarychanges are very interface dependant i.e. only applicable to the Smart Client ( i.e. Form ) OLTP interface. It would bepossible to store all additional business rules within client side packaged procedures but this would prevent such codefrom being used by other interfaces e.g. Web, batch processes etc. It is therefore recommended that where possible, suchrules are stored as package procedure Application Program Interfaces ( APIs ) on the server.

APIs

APIs are part of the Oracle Applications development methodology for its multi-tiered architecture. Papers have alreadybeen presented in the past about exactly what these routines are and why it is important to have code located on theserver. Hence, I will not be covering such topics in any depth in this paper. The remainder of this section regarding APIsis Oracle HRMS specific.

Oracle Human Resources and Oracle Payroll have implemented APIs using stored package procedures. They arebusiness processes which contain full data validation and manipulation. This development methodology enablesintegration with client applications such as Web and Forms interfaces. Their flexibility provides an open interface forother uses such as initial data loading and product customization.

In Release 10 of the Oracle HRMS Applications Smart Client suite, instead of developing another standalone interface (as had been done with Release 9 of the Oracle Applications using Oracle Forms 2.3 ), HRMS Development started tochanged its development methodology. New standards were created for implementing a set of programs to centralise thevalidation and processing logic on the server. In the long term avoiding duplication of development and maintenanceeffort by Oracle Applications across different end user interfaces. These user interfaces would be easier to implement astheir database work is carried out by calling the new APIs. At the same time providing a reliable open interface whichcan be used directly by Oracle consultants and customer implementation teams.

Module Structure

The API structure is designed around the business processes that we expect customers wish to perform within theapplication. Each API carries out one complete business operation; instead of providing insert, update and deleteprocedures for every database table in the application. This approach encapsulates all the database changes which needto be carried out for a single business process. This helps hide the complexity of the database structure and makes theAPIs easier to use. For example, when a new employee is entered on to the system, data may be inserted in to 6 databasetables. All the individual insert statements are grouped in to one ‘create employee’ API. Therefore this logic does nothave to be duplicated and maintained in both the form and other interface e.g. Web. Using APIs in Forms does notnegate the need for client side validation. Forms 4.5.7 contains graphical features such as check boxes and list of valueswhich prevent invalid values from being entered.

Oracle HRMS API Layers

Within the HRMS application suite, different categories or types of APIs have been identified and are used to enable themodular and structured ( building block ) construction of business process rules. This can best be representeddiagramatically:

Oracle HRMS API Layers

This ‘layered’ architecture and the fact that customer calls to ‘published’ business process APIs are allowed opens up theability to write custom business processes that interface with the application in a totally supported and upgradeablemanner. The published APIs therefore can be used as building blocks to construct custom APIs. For example, supposethat when a new employee joins your company you always obtain their home address at that time. The address detailsmust be recorded in the HR system because you run reports which expect every employee to have an address. You couldwrite your own business process API to create new employees with an address. This API is like a ‘wrapper’ that holdstogether everything that is important to the operation. Such an API could call the standard ‘create_employee’ API andthen immediately afterwards call the standard ‘create_person_address’ API.

Client-Side

Server-Side

Database

APIs

Programs

Business Process LayerE.G. create_employee

Custom / Alternative Interface LayerE.G. create_gb_employee

Business Support LayerE.G. create_emp_asg

Row Handler LayerE.G. per_people_f Table

‘Wrapper’ forcreate_employeewith GB flexfieldsegment names

PublishedAPIs

OracleApplicationsinternal codelayers

‘Wrapper’ Module Construct

Being able to call standard APIs within a supported framework highlights even more of the unique flexibility’s of theOracle Applications. But, what if your business rule was associated with a very specific process e.g. creating anemployee, and you wanted to able to influence the success or failure of the creation of the employee record(s) dependingon whether your custom rule(s) were successful or not. Because of such a requirement, the Oracle HRMS Applicationdevelopment team developed the concept of ‘API User Hooks’ ( this facility is only available within the HRMSapplication suite ).

Oracle HRMS Application User Hooks

In Release 11 of the Oracle HRMS Application suite, a subset of application APIs will support the execution of userdefined custom business through a mechanism known as ‘API User Hooks’. These hooks let you extend the standardbusiness rules that are executed by the core APIs. Custom specific validation rules or further processing logic can becreated and this will be executed automatically whenever the associated API is executed.

User hooks are locations in the APIs where extra logic can be executed. When the API processing reaches a user hook,the main processing will stop and any custom logic will be executed. Then, assuming no errors have occurred, the mainAPI processing will continue.

All extra custom logic that is needed is implemented as separate server-side package procedures using PL/Sql. Havingwritten additional logic, these procedures need to be associated with the pre-defined user hook points.

User hooks are only supported at specific business process and row handler API layers. There are different user hookevent points depending on the layer.

HRMS API User Hook Points

The linking of the Oracle Application APIs and the hooked custom developed APIs is done through ‘hook package body’procedures. These procedure bodies are generated by running an Oracle Application utility. This utility determines whatuser defined custom package procedures to link to what API user hooks by extracting user hook definitions fromdefinition tables. The utility then generates the hook package body procedure and the custom code is now ‘hooked’ to thestandard API code. For a more detailed description of this process see the Release 11 HRMS API Technical ReferenceManual essay.

HRMS API user hooks provide you with the ability to transplant your unique business process rules right within theheart of the application to where they are needed without losing Oracle support of the application.

custom_create_company_employee

create_person_address API(Standard HR API)

create_employee API(Standard HR API)

person_idaddress_line1 etc..person_id etc..

last_namefirst_name etc..

Row Handler LayerE.G. per_people_f Table

Business Process LayerE.G. create_employee

CoreLogic

AfterProcessHook

BeforeProcessHook After Delete Hook

After Update Hook

After Insert Hook

The next logical step would be able to store rules in some sort of dictionary and to be able to automatically generatePL/Sql package procedures that can be hooked in to the core APIs. This was considered important enough that theHRMS Application development group developed a ‘Fast Formula PL/Sql Execution’ engine that will be part of Release11 of the applications. This feature is unique to the Oracle HRMS Application suite.

Oracle HRMS Fast Formula PL/Sql Execution Engine

A core module of the Oracle HRMS Applications suite is the Fast Formula application. Formulas are generic expressionsof rules, calculations or comparisons that you may want to perform. They can take input and return values or messages.Formulas were typically used in Release 10 of the Oracle Applications Smart Client application to define computationalcalculations and input validation for Payroll processes. Formulas are written in their own ‘English’ like syntax and istherefore positioned to be an end user tool. Being able to generate and execute formulas in PL/Sql now means that non-technical users can assist in the generation and maintenance of user defined business rules that govern the application.Being able to store rules in a non-technical structure in a formula dictionary greatly reduces the overhead of businessrule creation, maintenance and overall cost of ownership. The PL/Sql formula routines are callable from client ( Forms )and server ( PL/Sql ) interfaces.

This feature is a major enhancement to the Oracle HRMS Application. As formulas are part of the core application, theyare supported during future software upgrades. There is no need to re-write the business rule because changes haveoccurred to the database schema. Such changes should be invisible to the end user as they will be handled by the coreapplication. This means that the overall cost of ownership of having such rules is greatly reduced compared to having tocustom write PL/Sql code to implement the rules yourself.

Business Rule Framework

This section is only applicable to the Oracle HRMS suite of applications.

So far we have looked at existing and new technologies and tools for the extension and enhancement of the OracleApplications. One problem in itself is that there are so many tools and techniques to choose from. Deciding which of thetools to use for what purpose is one of the first decisions that will have to be made.

As stated earlier in the paper, business rules should ideally be interface independent. The goal is to have one set of codethat performs the same rules whether it is being called from a form or some other type of interface ( e.g. batch process ).Because most of the existing Release 10 and Release 11 HRMS application forms call different server side packages tothe published user supportable APIs, it is not sufficient to assume that by just using user hooks to define custom rulesthat all possible system interfaces will be accommodated by the new rules. The custom library thus has an important partto play to link the OLTP forms to the hooked user defined rules. This can best be represented diagramatically showingwhat I am proposing to be a framework for custom business rules. The arrows represent possible program flows.

Business Rule Framework

The goal is to ensure that where possible, all business rules are created as package procedures stored within the database.Some business rules may be interface dependent and so it may be necessary to have specific rules within the customlibrary ( e.g. visual attribute rules ).

Form

CustomLibrary

BatchProcesses

Data Model

Core HRMS APIs

Hooked Code

User Defined APIs + PL/Sql Formula APIs

Database

CustomBusinessRules

The custom library should be used to call custom hooked business rules and any OLTP dependent rules ( that may onlyexist within form libraries ). There is a sizing limitation to the custom library ( as with any Oracle Form library ) and socareful consideration must be given to the design and construct of the custom library and any other attached / associatedlibraries. If you expect to have a lot of custom library code then it is advisable to partition the code within multiplelibraries. For example, create libraries by associating them with forms.

Custom Library Partitioning

Depending on how much custom code is associated with each form, it may be necessary to create further sub-libraries.Note that there will be a trade off between OLTP system performance and ease of maintenance of libraries. The morelibraries created, the greater the potential effect on on-line performance. Partitioning libraries in to associated forms willease the manageability and development of code by enabling related functional modules to be worked on independentlyof others. When upgrading the application, user defined libraries can easily be identified and check for compatibilitywith the new release. Of course, the old custom library ( with your calls to your custom libraries ) will have to be backedup during future upgrades to prevent losing some of your own code.

Implementation of Business Rule Categories

Earlier in this paper a number of business rule categories were presented ( with each category being given an associatednumber ). The following is a guideline as to what tools, technologies and techniques I would consider using to constructthe associated business rule(s). Even though I have listed different tools and techniques for each grouping of rules, thisdoes not imply that you need to use all of the tools and techniques in order to implement the rule. This will depend onthe complexity of the individual rule.

Custom Library and/or Hooked APIs and/or User Defined APIs

1.1.1 1.1.2 1.1.3 1.1.4 1.2 1.3.1 1.3.2 1.3.3 2.3

Custom Library and/or Application Security Features

1.3.4

Custom Library and/or Hooked APIs and/or User Defined APIs and/or PL/Sql Formula APIs

2.2 3

Custom Library and/or Hooked APIs and/or User Defined APIs and/or Oracle Workflow and/or Oracle Alert

2.1 4

As can be seen, the majority of the rules require the use of the custom library and API user hooks. The goal is to build onto the core application by extension rather than core application modification i.e. changing the logic of the core formsdirectly.

If block_name=’PER’ then ….Else ….End if;

If form_name=’PERWSEPI’ then perwsep_custom(event);Else ….End if;

‘PERWSEPI_CUST’ Custom LibraryCustom Library

Conclusion

We have seen that the Oracle Applications continue to advance in terms of development tools, technologies andtechniques. The custom library provides a non invasive mechanism that allows customers to extend the application in amanageable and controlled environment whilst preserving support for the core application. The ability to turn customlibrary code on or off ensures application support when problems are encountered as it enables you to identify whetherthe problem is custom code related or core application related.

The Oracle HRMS application suite, by providing API user hooks and PL/Sql generatable by Oracle Fast Formulas,extends the extensibility of the application within a controlled environment to yet unchartered dimensions. Gone are thedays of having to lose support for key features of the application in order to satisfy business requirements because youjust ‘had to’ modify a code module. It is now possible to do what was once impossible. This is due to Oracle’srecognition of its customers who are all unique in one way or another and therefore want flexible and extendiblesolutions without jeopardizing the core application.

The decision to custom build an application rather than buy something ‘off the shelf’ is no longer Black and White.Oracle, with its new breed of applications, is demonstrating that it is possible to extend the core application to satisfythat missing 5, 10, 15, 20.. percent business requirement fit in a manner that won’t destabalise the underlyingapplication and therefore provides a massive head start compared to custom building an application from scratch.

About the Author:

Andrew McGhee ( [email protected] ) has been involved with Oracle Applications for more than 6 years and hasbeen responsible for past HRMS beta programs, working closely with customers from all over the world. He also workedalong side Motorola in Europe during their pan European Oracle HR roll out. At present Andrew is involved with a U.S.organization in the largest ever Oracle HR implementation in the World ( more than 1.2 million person records ) as wellas working with a U.K. organization to implement Oracle Payroll for 120,000 people ( Oracle UK’s current largestPayroll implementation ).

APPENDIX 1

Useful Information About the Custom Library in Production 16.1

Custom Library Fundamentals

• You cannot change the specification of the CUSTOM package• You cannot attach the APPCORE library to the CUSTOM library• Use FNDSQF library whenever possible for function security, flexfields and message procedures• You cannot use SQL in the CUSTOM library ( call server side packages instead )• The CUSTOM library is global to all of the Oracle Applications and has no context associated with it• Do not use CALL_FORM or OPEN_FORM within the CUSTOM library, use FND_FUNCTION package instead• Function APP_ITEM_PROPERTY is not available within the CUSTOM library, user Oracle Forms

SET_ITEM_PROPERTY instead• Important bugs I encountered when working with the CUSTOM library

523460: Exceptions raised in custom when-validate-record events are not propagated to the calling code

480675: WHEN-VALIDATE-RECORD event missing from Oracle HRMS Position Form

• • Follow the Oracle Applications Coding standards !!• • Document EVERYTHING you do !!

Things I wish I had known before using the Custom Library

• More detailed knowledge about Developer 2000• More detailed knowledge of how to code Packages and Procedures• Form processing logic and triggers i.e. what gets fired when• How to build basic application compatible forms• Detailed processing logic and database objects used by Forms I extended• The difference between .plx and .pll library files

Appendix 2 - CUSTOM.pll

Package Header

PACKAGE custom IS

function zoom_available return BOOLEAN; function style(event_name varchar2) return integer; procedure event(event_name varchar2); before constant integer := 1; after constant integer := 2; override constant integer := 3; standard constant integer := 4;

END custom;

Package Header

package body custom is -- -- Customize this package to provide specific responses to events -- within Oracle Applications forms. -- -- Do not change the specification of the CUSTOM package in any way. -- You may, however, add additional packages to this library. -- -------------------------------------------------------------------- function zoom_available return boolean is -- -- This function allows you to specify if zooms exist for the current -- context. If zooms are available for this block, then return TRUE; -- else return FALSE. -- -- This routine is called on a per-block basis within every Applications -- form from the WHEN-NEW-BLOCK-INSTANCE trigger. Therefore, any code -- that will enable Zoom must test the current form and block from -- which the call is being made. -- -- By default this routine must return FALSE. -- /* Sample code: form_name varchar2(30) := name_in('system.current_form'); block_name varchar2(30) := name_in('system.cursor_block'); begin if (form_name = 'DEMXXEOR' and block_name = 'ORDERS') then return TRUE; else return FALSE; end if; end zoom_available; */ -- -- Real code starts here

-- begin return FALSE; end zoom_available;

--------------------------------------------------------------------

function style(event_name varchar2) return integer is -- -- This function allows you to determine the execution style for some -- product-specific events. You can choose to have your code execute -- before, after, or in place of the code provided in Oracle -- Applications. See the Applications Technical Reference manuals for a -- list of events that are available through this interface. -- -- Any event that returns a style other than custom.standard must have -- corresponding code in custom.event which will be executed at the -- time specified. -- -- The following package variables should be used as return values: -- -- custom.before -- custom.after -- custom.override -- custom.standard -- -- By default this routine must return custom.standard -- -- Oracle Corporation reserves the right to change the events -- available through this interface at any time. -- /* Sample code: begin if event_name = 'OE_LINES_PRICING' then return custom.override; else return custom.standard; end if; end style; */ -- -- Real code starts here -- begin return custom.standard; end style;

--------------------------------------------------------------------

procedure event(event_name varchar2) is -- -- This procedure allows you to execute your code at specific events -- including: -- -- ZOOM -- WHEN-NEW-FORM-INSTANCE

-- WHEN-NEW-BLOCK-INSTANCE -- WHEN-NEW-RECORD-INSTANCE -- WHEN-NEW-ITEM-INSTANCE -- WHEN-VALIDATE-RECORD -- -- Additionally, product-specific events will be passed via this -- interface (see the Applications Technical Reference manuals for -- a list of events that are available). -- -- By default this routine must perform 'null;'. -- -- Oracle Corporation reserves the right to change the events -- available through this interface at any time. -- /* Sample code:

form_name varchar2(30) := name_in('system.current_form'); block_name varchar2(30) := name_in('system.cursor_block'); param_to_pass1 varchar2(255); param_to_pass2 varchar2(255);

begin

-- Zoom event opens a new session of a form and -- passes parameter values to the new session. The parameters -- already exist in the form being opened.

if (event_name = 'ZOOM') then if (form_name = 'DEMXXEOR' and block_name = 'ORDERS') then param_to_pass1 := name_in('ORDERS.order_id'); param_to_pass2 := name_in('ORDERS.customer_name'); fnd_function.execute(FUNCTION_NAME=>'DEM_DEMXXEOR', OPEN_FLAG=>'Y', SESSION_FLAG=>'Y', OTHER_PARAMS=>'ORDER_ID="'||param_to_pass1|| '" CUSTOMER_NAME="'||param_to_pass2||'"');

-- all the extra single and double quotes account for-- any spaces that might be in the passed values

end if;

-- This is an example of a product-specific event. Note that as -- of Prod 15, this event doesn't exist. elsif (event_name = 'OE_LINES_PRICING') then get_custom_pricing('ORDERS.item_id', 'ORDERS.price');

-- This is an example of enforcing a company-specific business -- rule, in this case, that all vendor names must be uppercase. elsif (event_name = 'WHEN-VALIDATE-RECORD') then if (form_name = 'APXVENDR') then if (block_name = 'VENDOR') then copy(upper(name_in('VENDOR.NAME')), 'VENDOR.NAME'); end if; end if; else null; end if;

end event; */ -- -- Real code starts here -- form_name varchar2(30) := name_in('system.current_form');

begin

-- -- The following call to the HRCUSTOM library was put in by the Release 11 HRMS Vision team. -- As the CUSTOM library is shared by ALL applications, it is good practice to call other -- 'user defined' libraries if it is likely that you will be extensively adding user defined -- logic to the custom library. -- -- Be aware that there will be a marginal performance overhead when you start to introduce -- calls to additional libraries. --

-- -- If the current form is a HRMS related form then call the user defined HRCUSTOM library. --

if substr(form_name,1,2) in ('PE','PY','PA','SS','OT','DT','FF','HR') then hrcustom.event(event_name); end if;

end event;

end custom;

Appendix 3 - HRCUSTOM.pll

Package Header

PACKAGE hrcustom IS

procedure event(event_name varchar2);

END hrcustom;

Package Body

/*

This 'user defined' library was created by the HRMS Release 11 vision team.

Its purpose is to control what sub user defined libraries are called. The sub libraries are called depending on the current form name. The CUSTOM library hiarachy is as follows:

CUSTOM | |

HRCUSTOM |

---------------------------------| |

HRCUST1 HRCUST2

perwshrg perwsepy perwsepi paywsmee perwsema perwsead

Other libraries could be added to this hierarchy if required.

*/

package body hrcustom is

procedure event(event_name varchar2) is

form_name varchar2(30) := name_in('system.current_form');

begin

if form_name in ('PERWSHRG','PERWSEPI','PERWSEMA') then hrcust1.event(event_name); elsif form_name in ('PERWSEPY','PAYWSMEE','PERWSEAD') then hrcust2.event(event_name); else

null; end if;

end event;

end hrcustom;

Appendix 4 - HRCUST1.pll

Package Header

PACKAGE hrcust1 IS


END hrcust1;

Package Body

/*

This library was created by the HRMS Release 11 vision team.

The library controls additional business rule validation for the following forms:

PERWSEPI - Person FormPERWSHRG - 'Mega' Person FormPERWSEMA - Assignment Form

*/

package body hrcust1 is


form_name varchar2(30) := name_in('system.current_form'); block_name varchar2(30) := name_in('system.current_block');

l_button_selected number default 1; l_legislation_code varchar2(5);

begin

---- Perform all additional custom library validation logic for the Person form ( PERWSEPI ) and new-- 'mega' form ( PERWSHRG ).--

if form_name in ('PERWSEPI','PERWSHRG') then

if block_name = 'PERSON' then

-- -- The following was created to overcome a current synchronization 'feature' with the -- version of NCA being worked on. When going in to the Person form, a value is written to -- the global, MESSAGES_ALREADY_SHOWN, that is checked before the messages are displayed -- in the WHEN-NEW-BLOCK-EVENT. --

if event_name = 'WHEN-NEW-FORM-INSTANCE' then

copy ('True','global.messages_already_shown');

end if;

if event_name = 'WHEN-NEW-BLOCK-INSTANCE' then

if name_in('global.messages_already_shown') = 'True' then

-- -- SCENARIO 1

-- -- When entering the person form, prompt the user as to whether they would like all of the -- required fields to be highlighted. For the purpose of this example we have stipulated that -- the following fields are the required; Last Name, Person Type, Gender, Employee Number, -- National Identifier, Ethnic Origin and Date Of Birth. --

-- Having decided whether the user wants the mandatory fields highlighted or not, a value is -- written to a GLOBAL variable, VISION_HIGHLIGHT_FLDS. This global is used to determine whether

-- to warn the user that they have forgotten to enter mandatory fields when saving / updating -- person records.

l_legislation_code := name_in('ctl_globals.legislation_code');

fnd_message.set_string('Would you like to highlight all required EMPLOYEE fields ? '); l_button_selected:=fnd_message.question(button1 => 'Cancel',

button2 => 'No', button3 => 'Yes', default_btn => 2,

cancel_btn => 1, icon => 'question');

fnd_message.show;

if l_button_selected = 3 then set_item_property('person.last_name',VISUAL_ATTRIBUTE,'SELECTED_DATA'); set_item_property('person.d_person_type_id',VISUAL_ATTRIBUTE,'SELECTED_DATA'); set_item_property('person.sex',VISUAL_ATTRIBUTE,'SELECTED_DATA'); set_item_property('person.employee_number',VISUAL_ATTRIBUTE,'SELECTED_DATA'); set_item_property('person.national_identifier',VISUAL_ATTRIBUTE,'SELECTED_DATA'); set_item_property('person.date_of_birth',VISUAL_ATTRIBUTE,'SELECTED_DATA');

-- -- Only highlight the Ethnic Origin field if we are operating in a US business group. --

if l_legislation_code = 'US' then set_item_property('person.ethnic_origin_us',VISUAL_ATTRIBUTE,'SELECTED_DATA'); end if;

copy('Y','global.vision_highlight_flds');

elsif l_button_selected = 2 then

copy('N','global.vision_highlight_flds'); else copy('N','global.vision_highlight_flds'); end if;

-- -- SCENARIO 3 -- -- When entering the person form, prompt the user as to whether they would like to hide the Mail To -- field. This example just shows how it is possible to remove fields from the form. -- -- It is not possible to remove field prompts using the custom library. Field prompts are part of a forms -- boiler plate text. If you wanted to change these prompts then you could either manually modify the form -- to display a different prompt or even remove the prompt all together. If you wanted to change / remove -- a number of boiler plate prompts then you should consider using Oracle Translation Manager ( OTM ) to

help -- you make the changes. OTM also acts as a dictionary of changes so that changes can be reapplied to -- existing or new versions of the forms ( which is especially useful when you need to reapply changes -- having upgraded the application ). --

fnd_message.set_string('Would you like to remove the Mail To field ? '); l_button_selected:=fnd_message.question(button1 => 'Cancel',

button2 => 'No', button3 => 'Yes', default_btn => 2,


fnd_message.show;

if l_button_selected = 3 then set_item_property('person.d_home_office',DISPLAYED,PROPERTY_FALSE); elsif l_button_selected = 2 then null; else null; end if;

copy ('False','global.messages_already_shown');

end if;

end if;

if event_name in ('POST-INSERT','POST-UPDATE') then

-- -- SCENARIO 4 --

-- When creating or updating person information, check whether the Last Name field is in upper case. -- If it isn't then prompt the user to ask whether they would like to convert it to upper case. If they -- answer Yes then automatically convert the field to upper case, otherwise leave the field alone. --

if name_in(‘ctl_globals.legislation_code’) = ‘GB’ then

if name_in('person.last_name') is not null then if upper(name_in('person.last_name')) != name_in('person.last_name') then

fnd_message.set_string('Persons Last Name field is not in upper case. Would you like to convert it to upper case? ');

l_button_selected:=fnd_message.question(button1 => 'Cancel', button2 => 'No', button3 => 'Yes', default_btn => 2,


fnd_message.show;

if l_button_selected = 3 then copy(upper(name_in('person.last_name')),'person.last_name'); elsif l_button_selected = 2 then null; else null; end if;

end if; end if;

end if;

-- -- SCENARIO 2 --

-- When creating or updating person information, check whether the user selected to highlight mandatory -- fields. If they did, check whether any of the selected mandatory fields contains a null value.

--

if name_in('global.vision_highlight_flds') = 'Y' then if name_in('person.last_name') is null or name_in('person.d_person_type_id') is null or name_in('person.sex') is null or name_in('person.national_identifier') is null or name_in('person.date_of_birth') is null or ( name_in('ctl_globals.legislation_code') = 'US' and name_in('person.ethnic_origin_us') is null ) then

-- -- The following logic is only performed if the Employee Type for the entered person is

-- "Employee". -- -- Having determined that at least one of the highlighted mandatory fields is null, prompt the user -- to ensure that values are entered for all of the fields. -- -- A different message is displayed depending on the the legislation of the business group the user -- is running in. --

if name_in('person.d_person_type_id') = 'Employee' then if name_in('ctl_globals.legislation_code') = 'US' then

fnd_message.set_string('You have not entered all required fields: Last Name, Gender, Person Type, SocialSecurity Number, Employee Number, Birth Date and Ethnic Origin’); fnd_message.show; elsif name_in('ctl_globals.legislation_code') = 'GB' then fnd_message.set_string('A required person field is null. Required fields are: Last Name, Person Type,Gender, Employee Number,National Insurance Number and Date Of Birth'); fnd_message.show; else fnd_message.set_string('A required person field is null. Required fields are: Last Name, Person Type,Gender, Employee Number,National Identifier Number and Date Of Birth'); fnd_message.show; end if;

-- -- Prevent the form from commiting

--

raise form_trigger_failure;

end if;

end if; end if; end if;

end if; end if;

--

end event;

end hrcust1;

Appendix 5 - HRCUST2.pll

Package Header

PACKAGE hrcust2 IS


END hrcust2;

Package Body

/*

This library was created by the HRMS Release 11 vision team.

The library controls additional business rule validation for the following forms:

PERWSEPY - Salary Administration FormPAYWSMEE - Element Entry FormPERWSEAD - Absence Form

*/

package body hrcust2 is


form_name varchar2(30) := name_in('system.current_form'); block_name varchar2(30) := name_in('system.current_block');

l_min_mkt_salary number; l_max_mkt_salary number; l_mkt_salary_message varchar2(150); l_earn_poten varchar2(60); l_earn_mesg varchar2(100);

l_absence_hours varchar2(10); l_hr_total number;

begin

---- Perform all additional custom library validation logic for the Salary Administration form ( PERWSEPY ).--

if form_name = 'PERWSEPY' then

if block_name = 'REVIEW' then

if event_name in ('POST-INSERT','POST-UPDATE') then

-- -- SCENARIO 4 -- -- When entering salary proposals for an assignment, check whether the proposed salary falls within

-- market salary minimum and maximum values as defined for each job. -- -- The Additional Job Details decsriptive flexfield needs to be set up as follows: -- -- First Segment: Market Salary Minimum -- Database Field = ATTRIBUTE1 -- Validation = < any value set that only allows you to enter numeric values > -- -- Second Segment: Market Salary Maximum -- Database Field = ATTRIBUTE2 -- Validation = < any value set that only allows you to enter numeric values > -- -- This scenario also uses server side procedures that were cerated as part of the VISION_CL_CODE -- package. -- -- Procesing Login: -- -- If the assignment that the salary proposal is being made for is associated with a Job then -- retrieve the markey salary minimum and maximum values from the descriptive flexfield ATTRIBUTE1 -- and ATTRIBUTE2 fields. The salary proposal approval date is used to select the correct assignment -- record. -- -- If the market salary minimum and maximum values are not null then check whether the entered salary -- proposal falls between these figures. If it does then everything is okay. It doesn't then display -- a mesage to the user informing them that the entered amounf does not fall between the minimum and -- maximum market salary values and display the minimum and maximum values. --

fnd_message.set_string('Comparing amount against market survey data’); fnd_message.show;

vision_cl_code.market_salary(p_assignment_id => to_number(name_in('global.g_assignment_id')), p_approval_date => to_date(name_in('review.change_date'),'DD-MON-YYYY'),

p_min_mkt_salary => l_min_mkt_salary, p_max_mkt_salary => l_max_mkt_salary );

-- -- If the l_min_mkt_salary and l_max_mkt_salary variable is 0 then the persons assignment is not

-- associated with a Job ( therefore don't display any warnings ). --

if ( l_min_mkt_salary is not null or l_max_mkt_salary is not null ) and ( l_min_mkt_salary != 0 or l_max_mkt_salary != 0 ) then if to_number(name_in('review.d_proposed_salary')) between nvl(l_min_mkt_salary,0) andnvl(l_max_mkt_salary,0) then null; else l_mkt_salary_message:='Proposed amount is outside of the market salary range for the job, minimum value ='||to_char(l_min_mkt_salary)||' maximum value = '||to_char(l_max_mkt_salary);

fnd_message.set_string(l_mkt_salary_message ); fnd_message.show;

end if; else null; end if;


---- Perform all additional custom library validation logic for the Element Entry form ( PAYWSMEE ).-- if form_name = 'PAYWSMEE' then

if block_name = 'ENTRY' then

if event_name in ('PRE-INSERT','PRE-UPDATE','PRE_UPDATE') then

-- -- SCENARIO 5 -- -- This example shows how it is possible to call a server side Formula PL/Sql routine to calculate -- a value and then use the returned value to update a user non-enterable element input value.

-- The Formula PL/Sql routine also returns a message that is displayed to the user. -- -- For this scenario you will have to set up the following data on your system: -- -- Element Entry: "Earnings Potential", non-recurring element with the following input values: -- -- Sequence Input Name User Enterable -- 1 Current Earnings Yes -- 2 Earnings Potential No -- -- -- Formula: CL_EARN_POTENTIAL -- -- Review to the definition of this formula within the Vision database -- -- Having entered a Current Earnings input value for the 'Earnings Potential' element, a server side package -- ( vision_cl_code.call_earn_poten_formula ) is called. This package is a 'wrapper' routine that -- executes an Oracle FastFormula ( from within PL/Sql ). --

if name_in('entry.element_name') = 'Earnings Potential' then

if name_in('entry.user_entry1') is not null then

-- Call the server side call_earn_poten_formula to...

vision_cl_code.call_earn_poten_formula(p_amount => to_number(name_in('entry.user_entry1')), p_session_date =>

to_date(name_in('ctl_globals.session_date'),'DD-MON-YYYY'),

p_assignment_id =>to_number(name_in('entry.assignment_id')), p_earn_poten => l_earn_poten, p_earn_mesg => l_earn_mesg );

copy(replace(to_char(round(nvl(to_number(l_earn_poten),1),2),'999999990.99'),' ',''),'entry.user_entry2');

copy(name_in('entry.user_entry2'),'entry.screen_entry_value2');

fnd_message.set_string(l_earn_mesg); fnd_message.show;

else

-- The Current Earnings field is empty ( null ) so we need to clear out any values that may be in the Euro -- Equivalent field.

copy('','entry.user_entry2'); copy('','entry.screen_entry_value2');

end if;

end if;


---- Perform all additional custom library validation logic for the Absence Form ( PERWSEAD ).--

if form_name = 'PERWSEAD' then

if block_name = 'ABA' then

if event_name in ('WHEN-VALIDATE-RECORD') then

-- SCENARIO 6 --

-- Calculate the FMLS 12 month rolling average for 'Family Leave' absence types.-- The rolling average is between the actual absence end and ( actual absence end date-- minus 365 days ).

-- -- If this check needs to performed for additional absence types then the following statement -- needs to be amended as well as the server side vision_cl_code.rolling_absence_details

-- procedure.--

if (name_in('aba.date_end') is not null and name_in('aba.c_type_desc') = 'Family Leave' ) then

vision_cl_code.rolling_absence_details(p_person_id => to_number(name_in('aba.person_id')),

p_abs_actual_end_date => to_date(name_in('aba.date_end'),'DD-MON-YYYY'),

p_abs_att_id =>to_number(name_in('aba.absence_attendance_id')),

p_absence_hours => l_absence_hours );

l_hr_total:=nvl(to_number(name_in('aba.absence_hours')),0)+nvl(to_number(l_absence_hours),0);

if name_in('aba.absence_hours') is not null then copy(to_char(round(l_hr_total/8,1)),'aba.attribute6'); copy(to_char(round(l_hr_total/8/5,1)),'aba.attribute7'); end if;

end if; end if;

end if; end if;

end event;

end hrcust2;

Appendix 6 - Server Side Custom Library Code ( server_cl_code.sql )

/*

File Header Information=======================

This package has been created to show how it is possible to make the custom libraryinterface with code on the server in order to perform additional business rulevalidation. It has been created specifically to work with the Oracle Application Visiondatabase, Release 11.

In this package I have built in the following procedures and functions:

Check Digit-----------

This routine calculates the check digit of a number using the modulus 11 algorithm

Market Salary-------------

This routine retrieves the market salary minimum and maximum amounts ( associated with ajob ).

Euro Conversion---------------

This routine retrieves the Euro currency exchange rate. There is no such currency as EUROwithin Oracle Applications 11. It is therefore necessary to create such a currency andto assign appropriate exchange rates to / from the currency. This routine relies on thefact that you have already set up the Euro currency ( using the System Asministratorresponsibility ) and created exchange rates within your business group against a Payrollcalled 'Monthly'.

Call Earnings Potential Formula-------------------------------

This routine shows how it is possible to call an Oracle Fast Formula PL/Sql formula fromthe custom library. The formula takes a single input, CURRENT_EARN ( current earnings ),and performs a calculation on the input and returns EARN_POTEN ( earnings potential ) andEARN_MESG ( earnings message ). The calculation set up is very simplistic but it makesuse of a database item, PER_AGE. Even though this is a very simple formula, it showssome of the features that are possible that can be accessed via the PL/Sql formula engine.The earnings message is displayed from within the custom library. It is therefore easyto show how you can change the calculation and message from within the formula and then showthe user instantly how the changes have taken affect when entering Earnings Potentialelement entries.

Rolling Absence Details-----------------------

This routine calculates the 12 month rolling total for the Family Leave absence type. Therolling period is taken from the absence 'actual end date'.

Install Instructions====================

This package must be created in the APPS Oracle schema in your database. This canbe done from the Unix prompt of your machine:

> sqlplus apps/<apps password> @server_cl_code.sql

If you want to make use of this package from with Secure User SQL*Plus accounts thenyou will need to:

1 - Grant execute on this package to roles HR_SECURE_USER and HR_REPORTING_USER

sqlplus apps/<apps password>

grant execute on vision_cl_code to hr_secure_user;

grant execute on vision_cl_code to hr_reporting_user;

2 - Create a public synonym for this package from within the SYSTEM SQL*Plus account

sqlplus system/<system password>

create public synonym vision_cl_code for apps.vision_cl_code;

Change List===========

Version Date Author Comments-------+------------+------------------+------------------------------------------------- 1.0 26-FEB-1998 A.McGhee Created

-----------------------------------------------------------------------------------------*/

---- Real code starts here.--

-- WhenEver SqlError Exit Failure Rollback;

create or replace package vision_cl_code as/* $Header:.... some header file details $ */

procedure check_digit (p_cd_number in varchar2 default null ,

p_check_digit out varchar2 );

procedure market_salary (p_assignment_id in number, p_approval_date in date, p_min_mkt_salary out number, p_max_mkt_salary out number );

procedure euro_conversion (p_business_group_id in number, p_session_date in date, p_element_type_id in number, p_euro_conv_rate out number);

procedure call_earn_poten_formula (p_amount in number default 0, p_session_date in date, p_assignment_id in number, p_earn_poten out varchar2, p_earn_mesg out varchar2 );

procedure rolling_absence_details (p_person_id in number, p_abs_actual_end_date in date, p_abs_att_id in number, p_absence_hours out varchar2);

end vision_cl_code;/

--------------/*

File Body Information=====================

This package has been created to show how it is possible to make the custom libraryinterface with code on the server in order to perform additional business rulevalidation. It has been created specifically to work with the Oracle Application Visiondatabase, Release 11.

In this package I have built in the following procedures and functions:

Check Digit

-----------

This routine calculates the check digit of a number using the modulus 11 algorithm

Market Salary-------------

This routine retrieves the market salary minimum and maximum amounts for a particularjob.

Euro Conversion---------------

This routine retrieves the Euro currency exchange rate. There is no such currency as EUROwithin Oracle Applications 10.7. It is therefore necessary to create such a currency andto assign appropriate exchange rates to / from the currency. This routine relies on thefact that you have already set up the Euro currency ( using the System Asministratorresponsibility ) and created exchange rates within your business group against a Payrollcalled 'Monthly'.

Call Earnings Potential Formula-------------------------------

This routine shows how it is possible to call an Oracle Fast Formula PL/Sql formula fromthe custom library. The formula takes a single input, CURRENT_EARN ( current earnings ),and performs a calculation on the input and returns EARN_POTEN ( earnings potential ) andEARN_MESG ( earnings message ). The calculation set up is very simplistic but it makesuse of a database item, PER_AGE. Even though this is a very simple formula, it showssome of the features that are possible that can be accessed via the PL/Sql formula engine.The earnings message is displayed from within the custom library. It is therefore easyto show how you can change the calculation and message from within the formula and then showthe user instantly how the changes have taken affect when entering Earnings Potentialelement entries.

Rolling Absence Details-----------------------

This routine calculates the 12 month rolling total for the Family Leave absence type. Therolling period is taken from the absence 'actual end date'.

Install Instructions====================

This package must be created in the APPS Oracle schema in your database. This canbe done from the Unix prompt of your machine:

> sqlplus apps/<apps password> @server_cl_code.sql

If you want to make use of this package from with Secure User SQL*Plus accounts thenyou will need to:

1 - Grant execute on this package to roles HR_SECURE_USER and HR_REPORTING_USER

sqlplus apps/<apps password>

grant execute on vision_cl_code to hr_secure_user;

grant execute on vision_cl_code to hr_reporting_user;

2 - Create a public synonym for this package from within the SYSTEM SQL*Plus account

sqlplus system/<system password>

create public synonym vision_cl_code for apps.vision_cl_code;

Change List===========

Version Date Author Comments-------+------------+------------------+------------------------------------------------- 1.0 26-FEB-1998 A.McGhee Created

-----------------------------------------------------------------------------------------*/

---- Real code starts here.--

WhenEver SqlError Exit Failure Rollback;

create or replace package body vision_cl_code as/* $Header:.... Some body file details $ */

-- Package Variables

g_package varchar2(33) := 'vision_cl_code.';

-- ********************************-- *** Procedure CHECK_DIGIT ***-- ********************************

---- Calculate the Modulus 11 check digit.--procedure check_digit (p_cd_number in varchar2 default null , p_check_digit out varchar2 )is

--

-- Declare cursor and local variables--

l_pos1 number default 0;l_pos2 number default 0;l_pos3 number default 0;l_pos4 number default 0;l_pos5 number default 0;l_pos6 number default 0;l_pos7 number default 0;l_pos8 number default 0;l_pos9 number default 0;l_added_total number default 0;l_remainder number default 0;l_check_digit number default 0;

begin

---- There are 5 steps to calculate the Modulus check digit.--

---- Step 1: Multiply each of the 9 digits by a weighting factor.--

l_pos1:=to_number(substr(p_cd_number,1,1)) * 10; l_pos2:=to_number(substr(p_cd_number,2,1)) * 9; l_pos3:=to_number(substr(p_cd_number,3,1)) * 8; l_pos4:=to_number(substr(p_cd_number,4,1)) * 7; l_pos5:=to_number(substr(p_cd_number,5,1)) * 6; l_pos6:=to_number(substr(p_cd_number,6,1)) * 5; l_pos7:=to_number(substr(p_cd_number,7,1)) * 4; l_pos8:=to_number(substr(p_cd_number,8,1)) * 3; l_pos9:=to_number(substr(p_cd_number,9,1)) * 2;

---- Step 2: Add the results of each multiplication together.--

l_added_total:=l_pos1 + l_pos2 + l_pos3 + l_pos4 + l_pos5 + l_pos6 + l_pos7 + l_pos8 + l_pos9;

---- Step 3: Divide the total from Step 2 by 11 and establish the remainder.--

l_remainder:=mod(l_added_total,11);

---- Step 4: Subtract the remainder from 11 to give the check digit.--

l_check_digit:=11-l_remainder;

---- Step 5: Validate the check digit.---- If the result from step 4 is 11 then a check digit of 0 is used.---- If the result from step 4 is 10 then the number is invalid.-- In this case I set the check digit value to I ( for Invalid ). This value-- gets passed back to the form and the custom library will display an-- appropriate message informing the user that the entered Person Number does-- not conform using the Modulus 11 algorithm.

if l_check_digit=11 then p_check_digit:='0'; elsif l_check_digit=10 then p_check_digit:='I'; else p_check_digit:=to_char(l_check_digit); end if;

end check_digit;

-- **********************************-- *** Procedure MARKET_SALARY ***-- **********************************

procedure market_salary (p_assignment_id in number, p_approval_date in date, p_min_mkt_salary out number, p_max_mkt_salary out number )is

---- Declare cursor and local variables--

cursor c_get_mkt_values is select to_number(nvl(pj.attribute1,0)), to_number(nvl(pj.attribute2,0)) from per_assignments_f paf, per_jobs pj where paf.assignment_id = p_assignment_id and p_approval_date between paf.effective_start_date and paf.effective_end_date and paf.job_id = pj.job_id;

begin

---- Find out whether the person has been associated with a Job on their assignment.

-- If they have, use the job_id value to join to the PER_JOBS table to retrieve the market-- salary minimum and market salary maximum values. These values are stored in ATTRIBUTE1-- and ATTRIBUTE2 on the Job Descriptive Flexfield.--

open c_get_mkt_values;fetch c_get_mkt_values into p_min_mkt_salary, p_max_mkt_salary;close c_get_mkt_values;

end market_salary;

-- ************************************-- *** Procedure EURO_CONVERSION ***-- ************************************

procedure euro_conversion (p_business_group_id in number, p_session_date in date, p_element_type_id in number, p_euro_conv_rate out number)is

---- Declare cursor and local variables--

-- Using the passed in parameters, retrieve the exchange rate value from the exchange-- rate table where the rate is associated with a payroll called 'Monthly' ( making sure-- that all effective dates are checked using the passed in session date ).---- If there is no entry in the exchange rates table where the 'From Currency' equals 'EUR'-- ( for Euro ) and the 'To Currency' equals the input currency code specified for the-- element type, then this routine returns null for the exchange rate.--

cursor c_get_euro_value is select pex.rate from pay_exchange_rates_f pex, pay_element_types_f pet,

pay_payrolls_f ppf where ppf.payroll_name = 'Monthly' and ppf.business_group_id = p_business_group_id and p_session_date between ppf.effective_start_date and

ppf.effective_end_date and pet.element_type_id = p_element_type_id and pet.business_group_id = p_business_group_id and p_session_date between pet.effective_start_date and

pet.effective_end_date and ppf.payroll_id = pex.payroll_id and pex.from_currency_code = 'EUR' and pex.to_currency_code = nvl(pet.input_currency_code,'USD') and p_session_date between pex.effective_start_date and

pex.effective_end_date;

begin

open c_get_euro_value; fetch c_get_euro_value into p_euro_conv_rate; close c_get_euro_value;

end euro_conversion;

-- ********************************************-- *** Procedure CALL_EARN_POTEN_FORMULA ***-- ********************************************

procedure call_earn_poten_formula (p_amount in number default 0, p_session_date in date, p_assignment_id in number, p_earn_poten out varchar2, p_earn_mesg out varchar2 )is

l_formula_id number; l_effective_date date; l_inputs ff_exec.inputs_t; l_outputs ff_exec.outputs_t; l_loop_cnt number; l_in_cnt number; l_out_cnt number; l_use_dbi_cache boolean default false;

begin

-- This procedure assumes that you have set up a formula with a single input -- called 'CURRENT_EARN' of data type NUMBER and two outputs, EARN_POTEN and EARN_MESG, -- of type VARCHAR2.

-- Set up some of the values we will need to exec formula. If your formula has a -- differnt Id then you need to change the value for l_formula_id.

-- The formula created is called CL_EARN_POTENTIAL and has Id 50931.

l_formula_id := 50931; l_effective_date := to_date('01-JAN-1997', 'DD-MON-YYYY');

-- Initialise the formula.

ff_exec.init_formula(l_formula_id, l_effective_date, l_inputs, l_outputs);

-- The input and output table have been initialised. We now have to -- set up the values for the inputs required. This includes both those -- for the 'inputs are' statement and any contexts. -- -- In our simple example we don't really need a 'for loop' as we know that there

-- is only one input specified for our formula. We could have just used l_inputs..first -- instead. -- -- Don't try and guess the input value number. It does not always start at '1'. --

-- Looking at the formula, you would see that there is only a single input, CURRENT_EARN -- but you'll notice that we are setting up inputs for ASSIGNMENT_ID and DATE_EARNED. -- This is because the formula uses database item PER_AGE which has contexts of -- ASSIGNMENT_ID and DATE_EARNED.

for l_in_cnt in l_inputs.first..l_inputs.last loop if(l_inputs(l_in_cnt).name = 'CURRENT_EARN') then l_inputs(l_in_cnt).value := p_amount; -- will implicitly convert. elsif(l_inputs(l_in_cnt).name = 'ASSIGNMENT_ID') then l_inputs(l_in_cnt).value := p_assignment_id; -- will implicitly convert. elsif(l_inputs(l_in_cnt).name = 'DATE_EARNED') then l_inputs(l_in_cnt).value := to_char(p_session_date,'DD-MON-YYYY'); end if; end loop;

-- Execute the formula.

ff_exec.run_formula(l_inputs, l_outputs, l_use_dbi_cache);

-- Now we have executed the formula. We are able to retrieve the results. --

for l_out_cnt in l_outputs.first..l_outputs.last loop if l_outputs(l_out_cnt).name = 'EARN_POTEN' then p_earn_poten:=l_outputs(l_out_cnt).value; elsif l_outputs(l_out_cnt).name = 'EARN_MESG' then p_earn_mesg:=l_outputs(l_out_cnt).value; end if; end loop;

-- Note: There is no procedure to be called to shut down the execution engine.

end call_earn_poten_formula;

-- ********************************************-- *** Procedure ROLLING_ABSENCE_DETAILS ***-- ********************************************

procedure rolling_absence_details (p_person_id in number, p_abs_actual_end_date in date, p_abs_att_id in number, p_absence_hours out varchar2)is

---- If any additional absence types get added that are required to be included in this-- calculation then you need to change (7) with (7,<new absence_attendance_type_id>)

-- e.g. (7,1234)--

---- I've added a check to make sure that the absence_attendance_id does not equal the-- absence_attendance_id passed in to the procedure, p_abs_att_id. This is because this-- routine may be called if a persons absence record gets updated on-line. In this case-- we don't want to sum up all absence records for the person because they may have changed the-- absence hours on-line and therefore the on-line value may differ from the value already-- written to the table.--

cursor c_cals_abs_total is select sum(nvl(paa.absence_hours,0)) abs_tot_hours from per_absence_attendances paa where paa.absence_attendance_type_id in (7) and paa.person_id = p_person_id and paa.date_end between (p_abs_actual_end_date-365) and p_abs_actual_end_date and paa.absence_attendance_id != nvl(p_abs_att_id,-9999);

begin

open c_cals_abs_total; fetch c_cals_abs_total into p_absence_hours; close c_cals_abs_total;

end rolling_absence_details;

end vision_cl_code;/

Vision Custom Lib

Documents

custom library scenarios

custom library code

single library

custom code

anystandard forms library

hrms release

oracle forms

copy of server