You are on page 1of 8

POR_CUSTOM_PKG

One of the common requirements in iProcurement implementation is to perform


custom defaulting or validating fields in requisition header/line/distribution
during Requisition creation. For example, you may want to default project value
based on requestor or validate deliver-to location to check if it is valid for a
project etc. The objective of the article is to share different approaches I learnt
from my experience, to achieve it.
I will take a simple requirement to explain each of the approaches and analyze
their pros and cons. My requirement in is as follows as. Please note I'm using
11.5.10.2 iProcurement.
Requirement:
Ive defined attributes (Attribute15) on requisition header and line with the name
Fund. Fund attribute on the line drives charge account generation. User is
required to enter fund on header in Checkout: Requisition Information page, this
value is defaulted or copied to fund attribute on the line. This means user
doesnt have to enter fund attribute for all the lines in the requisition, in fact fund
on line is not displayed unless it is shown using OAF Personalization (DFFs are by
default not shown in OAF page). Only Fund attribute on header is displayed by
setting Rendered property to true for item ReqHeaderDFF using OAF
Personalization. Fund on requisition header in Checkout page is shown in the
below screenshot.

Solution Approach:
Different solution approaches for addressing the above requirement are:
POR_CUSTOM_PKG:
This is Oracle seeded package provided as a hook to include custom defaulting
and validation logic in iProcurement requisition creation.
Extending Application Module and Controller of Checkout page using
OAF extension:
Create a method to copy fund from header to line in extended application
module. Extend controller to make a call to that AM method during page events
like Edit Lines, Submit etc.
Extend existing Helper / Server Command classes using OAF:
iProcurement OAF architecture is designed to use Server Command and Helper
classes to encapsulate the business logic. These additional classes contain code
that would normally be placed in Application Module. The code is separated to
prevent AM from growing too big and promote reusability. We can extend these
classes to place custom logic to meet our requirement. This approach requires
good understanding of OAF and its integration with underlying BC4J components.
I will use above approaches to implement my requirement, and point out some
limitations of each approach. This first article in the series has implementation
using POR_CUSTOM_PKG.
Approach 1: POR_CUSTOM_PKG:
POR_CUSTOM_PKG provides customization hooks to perform the defaulting logic
and validation of the requisition header, line, and distribution data. The
procedures in this package are called during requisition creation in iProcurement.
Requisitions created in Purchasing module doesnt use this package.
The procedures are invoked from CustomReqHeaderHelper,
CustomReqLineHelper, and CustomReqDistHelper classes which implements
interface classes PoRequisitionHeaderEOHelper, PoRequisitionLineEOHelper, and
PoReqDistributionEOHelper respectively. Without going too much into details of
their implementation, let us look at different pl/sql procedures available in
por_custom_pkg.
This package contains 7 procedures (3 for defaulting logic, 3 for validations and 1
for updating charge account). Function of each procedure is self explanatory by
looking at their names; I will give a gist of each of them:
Procedure Name

Purpose

CUSTOM_DEFAULT_REQ_HEADER

CUSTOM_VALIDATE_REQ_HEADER

CUSTOM_DEFAULT_REQ_LINE

CUSTOM_VALIDATE_REQ_LINE

CUSTOM_DEFAULT_REQ_DIST

CUSTOM_VALIDATE_REQ_DIST

CUSTOM_UPDATE_CHARGE_ACCOUNT

Customize it to include header


defaulting logic. It is called when new
requisition is created from scratch or
copied from old requisition. Header DFF
attributes are available to use.
Customize it to include header
validation logic. This validation would
in addition to all validations done for
requisition header. It is called when
new requisition is submitted / saved.
Customize it to include Line defaulting
logic. It is called when new requisition
line is created. Header information plus
line information including DFF
attributes are available to use.
Customize it to include Line validation
logic. It is called when new requisition
line is submitted / saved.
Customize it to include distribution
defaulting logic. It is called when new
distribution is created.
Customize it to include distribution
validation logic. It is called when new
distribution is submitted / saved.
Overrides default charge account. Use
PO Account Generator workflow instead
of this procedure. This procedure
doesnt execute at all.

The above defaulting and validation procedures has common OUT parameters
x_return_code and x_error_msg. These parameters can be used to return the
results of the validation. Return code (x_return_code) can be used to indicate on
which tab error message to be displayed to Edit Lines page.
If result code is 1, error is displayed on the Delivery tab
If result code is 2, error is displayed on the Billing tab
If result code is 2, error is displayed on the Accounts tab
These procedures are by default do not have any implementation. Once custom
code is placed, three profile options control whether customization takes effect
on existing requisition process.
The profiles are:
POR: Enable Req Header Customization
POR: Enable Requisition Line Customization

POR: Enable Req Distribution Customization


These profiles have to be set to Yes at site level, to tell iProcurement to execute
customization in corresponding procedures.
Implementation:
Going back to my requirement of copying fund value from header to line,
implementation requires: Coding defaulting procedure for requisition line i.e.
CUSTOM_DEFAULT_REQ_LINE
Profile POR: Enable Requisition Line Customization need to be set to Yes at
site level.
In POR_CUSTOM_PKG.CUSTOM_DEFAULT_REQ_LINE procedure, header fund value
is available in header attribute15 i.e. IN parameter header_attribute_15, copy its
value to line fund value i.e. IN OUT parameter x_attribute15. Return 0 at the end
to signal success. Below screenshot shows implementation of the procedure.

Advantages of this approach are it is simple and doesnt require developer to


have understanding of OAF or Java. If customization needs to turned off, clear
the profile POR: Enable Requisition Line Customization value or set it to No at
site level.
Limitations of this approach is defaulting procedures are only executed when
requisition is first created. If the user changes fund value in header, new value is
not copied to line because default procedure is not executed. So this
implementation doesnt fully solve the purpose.
A similar example where defaulting fails is, suppose you want to default a value
say 0000000 to header fund when requisition is created. We can code
POR_CUSTOM_PKG. CUSTOM_VALIDATE_REQ_HEADER to copy 0000000 to

x_attribute15 if it is null. This works when requisition is created from scratch in


Non-catalog request page or by selecting inventory item. iProcurement create
new records in requisition header (po_requisition_headers_all) and line
(po_requisition_lines_all) tables when checkout is done. Suppose you change
fund value to 1234567, save it, delete lines in requisition and start over from
Non-catalog request page, default value 0000000 is not shown for fund instead
1234567 is shown. iProcurement doesnt delete requisition header when lines
are deleted. It uses existing header record i.e. same req_header_id which means
default header procedure is not executed. These are few scenarios where I felt
default procedures doesnt work the way I wanted it to be. So I have to opt for
alternative solution.
The next article in the series uses OAF extension of controller and application
module to implement my requirement.

FAQ: POR_CUSTOM_PKG (PORCUSTB.pls) For Implementing Default and


Validate Customizations in iProcurement Requisition Headers, Lines,
and Distributions (Doc ID 1942913.1)

1. What are the profiles relevant to POR_CUSTOM_PKG?


Enable some or all of the relevant profiles to activate the custom logic
implemented in POR_CUSTOM_PKG at Header, Line, and/or Distribution level
POR: Enable Req Header Customization
POR: Enable Requisition Line Customization
POR: Enable Req Distribution Customization
2. Is it necessary to bounce oc4j (iAS/Apache) for the 'POR: Enable Req
%Customization' profile changes to take effect?
Yes, it is necessary to bounce oc4j (iAS/Apache) for these profiles to take effect
3. How can the custom package be used to default DFF line level
attributes from header level DFF attribute values?
Use the CUSTOM_DEFAULT_REQ_LINE procedure in POR_CUSTOM_PKG
(PORCUSTB.pls) to implement custom logic to default the requisition header DFF
value to a requisition line DFF value.
The procedure provides header_attribute_1 through header_attribute_15 as
INPUT (IN) variables from the requisition header, and allows you to specify

custom logic for the x_attribute1 through x_attribute15 IN OUT line level
variables as OUTPUT.
For example:
If you want the header_attribute_7 header value to be assigned to x_attribute8 at
the line level, use the following statement in the CUSTOM_DEFAULT_REQ_LINE
procedure
BEGIN
x_attribute8 := header_attribute_7;
X_RETURN_CODE:=0;
X_ERROR_MSG:='';
END;
Implement the above logic in POR_CUSTOM_PKG.CUSTOM_DEFAULT_REQ_LINE.
Or you may add more complex logic if you prefer. You will have to contact
Consulting or Partners for assistance with more complex logic if desired.
4. How do you modify the POR_CUSTOM_PKG code?
You may modify the POR_CUSTOM_PKG.CUSTOM_DEFAULT_REQ_LINE directly in
the database. Or you may modify the
POR_CUSTOM_PKG.CUSTOM_DEFAULT_REQ_LINE in file
$ICX_TOP/patch/115/sql/PORCUSTB.pls and then upload the revised package to
the database.

If you modify the file PORCUSTB.pls, then you may use these commands to load
the revised package to the database.
cd $ICX_TOP/patch/115/sql
sqlplus apps/apps
SQL> set define off;
SQL> @PORCUSTB.pls
SQL> commit;
5. Is the POR_CUSTOM_PKG used only for updating DFF attributes, or
can it be used for updating other values on requisitions?
POR_CUSTOM_PKG can be used for updating other valus as well. Review the
specific Header, Line, or Distribution DEFAULT procedure in the custom package
and see the IN OUT values available for update. As a general rule of thumb IN
values are Read Only, but IN OUT values may be updated by the
POR_CUSTOM_PKG (there may be a few exceptions).
6. Is it necessary for the user to navigate to a page where the DFF
attributes or other field values are enabled in order for the
POR_CUSTOM_PKG to be called?

Yes, the user must navigate to the page where the DFF value is active for the
customization in POR_CUSTOM_PKG to be called. You may enable the Requisition
Header DFF Additional Header Information, Requisition Line DFF Additional Line
Information, and Requisition Distribution DFF Additional Distribution Information
on the Checkout page to get the relevant POR_CUSTOM_PKG procedures to be
called at checkout step 1. The users navigate to this page each time they
checkout a requisition in iProcurement so the relevant POR_CUSTOM_PKG
procedures would be called accordingly.
7. How is personalization implemented to show DFF attributes
referenced in the POR_CUSTOM_PKG?
For Example:
Navigate to iProcurement checkout step 1 of 3
Click Personalize Page
Complete / Expance All
Search the page for - Row Layout: (ReqLineDFFRow)
Click the Edit (pencil) icon
Set Rendered = True
Click Apply
Click Return to Application (lower left of page)

With the above personalization implemented, the 'Additional Line Information'


section at the bottom of the Checkout step 1 of 3 can be used to enter the Line
level DFF value, and this will apply to all lines on the requisition. Similar
personalization can also be implemented for header and distribution level DFFs.
8. Are the POR_CUSTOM_PKG.CUSTOM_DEFAULT... procedures called
when there is an update to the requisition header, line, or distribution?
The CUSTOM_DEFAULT_REQ_HEADER, CUSTOM_DEFAULT_REQ_LINE, and
CUSTOM_DEFAULT_REQ_DIST procedures are not called when there is an update
to a requisition header, line, or distribution value. These are DEFAULT
procedures, and are ONLY called when a new requisition Header, Line, or
Distribution is created. They are not called upon update. There is
documentation within the PORCUSTB.pls for each procedure describing when
that procedure is called. Review the PORCUSTB.pls code comments for more
information.
9. Can the POR_CUSTOM_PKG.CUSTOM_VALIDATE... procedures be used
to UPDATE values?

The CUSTOM_VALIDATE_REQ_HEADER, CUSTOM_VALIDATE_REQ_LINE, and


CUSTOM_VALIDATE_REQ_DIST procedures may not be used for updating values.
These procedures only provide IN parameters (except for the result_code and
x_error_msg) so there is no option to UPDATE values using these procedures. You
may add validation logic in the POR_CUSTOM_PKG Validation procedures to verify
the DFF attribute data and other data meets your validation requirements. If the
data does not comply with your requirements, you may throw an error advising
which data needs to be manually corrected by the user before proceeding and
completing checkout and submit. The user will not be allowed to submit the
requisition until all the validations pass, but the ...VALIDATE... procedures cannot
programatically update any values. The user must update the values manually
based on the error details provided by the validation x_error_message.