Professional Documents
Culture Documents
11.5.10 - Ip - Architecture v2
11.5.10 - Ip - Architecture v2
June 2005
1
11.5.10: Oracle iProcurement Architecture Review
INTRODUCTION
This paper provides a high level overview of the 11.5.10 - iProcurement architecture and should provide valuable insight to
customers in designing customizations to the product. This document assumes that the reader is completely well versed
with the Oracle Applications Framework (OAF) and its integration with underlying Oracle Business Components For Java
(BC4J) architecture.
The following documents provide a good overview of the OAF and BC4J architecture and are a pre-requisite to reading
this document.
This document would provide some insight into implementing the last two categories of customizations using the iProcurement
architecture. The first three categories can be implemented using the standard OAF architecture and is beyond the scope of this
document.
Hiding/Displaying/Disabling
Attributes on a given page
The OA Personalization
Re-ordering the attributes displayed Framework provides support for
on a page all the listed customization
options.
Changing the label/prompt
associated with a given attribute
Adding new validation rules for the This can be implemented using the Addressed in this document
attributes on the requisition header, Helper Classes as described in this
line and/or distribution document, in the BC4J
2
11.5.10: Oracle iProcurement Architecture Review
ARCHITECTURE OVERVIEW
In this section, we briefly describe the interactions between the different layers in the new iProcurement architecture, each time
a page is displayed or the information on a page is submitted. More specific details about each of the layers of the architecture,
the implementation details and design/customization guidelines are explained below.
Controlled By
Web Web
Bean Bean
processFormRequest
xml Page
Application Module
2 2
Server Tier
3
Server View Object
Command 3
4 4
6
5
Database
Schema
1. When a page is displayed, the OAF will automatically call the processRequest method on the Controller of a page. In
certain cases, in addition to the statically rendered items on a page, there are dynamically controlled elements that are
displayed based on other setup in the system. If this logic is simple, then the corresponding implementation would be
in the Controller for the page (Step 1).
3
11.5.10: Oracle iProcurement Architecture Review
2. In many cases, the logic to determine the state of the dynamic elements on the page is sufficiently complex to warrant
new Server Commands (refer to the “Server Command” section on Page 7 for more details) to encapsulate the logic. In
this scenario, a call is made from the Controller to the Server Command via the corresponding Application Module
(AM) for the transaction. The Application Module maintains a mapping of the Server Command names and the
corresponding classes. The Controller passes the name of the Server Command to the Application Module, which in
turn uses the mapping to execute the Server Command (Step 2).
3. The Server Command then calls the corresponding View Object (VO), which in turn calls the mapped Entity Object
(EO), to retrieve the data required to determine which elements and data values to be displayed on the page (Steps 3, 4
and 5).
1. When the data on the page is submitted (for e.g. when a button on the page is clicked), OAF calls the
processFormRequest on the Controller for the page. In most cases, all the processing that needs to be done once a page
is submitted is implemented in Server Commands (Step 1).
2. Depending on the event being processed by the Controller, the Controller passes the name of the Server Command to
the Application Module, which in turn makes a call to the corresponding Server Command (Step 2).
3. In most cases, the data submitted on a page needs to be validated before the user proceeds to the next page in the flow.
All the validation logic is implemented in Helper classes (refer to the “Helper” section on Page 14), which can be
associated with one or more Entity Objects. The Server Command calls methods in the Helper classes to perform all
the required validations on the page. Helpers might use additional criteria (Business Attribute Sets and Business Views
as explained in Pages 10 and 11) to determine which validation needs to be performed on a given page (Steps 3, 4, 5
and 6).
CONTROLLERS
Overview
The Controller responds to user action and controls the application flow. Each page in the application has at least one
Controller associated with it.
The list of all the Controllers invoked in the requisition checkout flow, along with the associated pages and descriptions is
as detailed below.
Shopping Cart ShoppingCartCO.java Users can access the page after items have been
added to the shopping cart.
Checkout – Summary CheckoutSummaryCO.java This is the first page in the Checkout flow after the
shopping cart. Users can submit requisitions from this
page.
4
11.5.10: Oracle iProcurement Architecture Review
Checkout – Edit Lines CheckoutLinesCO.java Users can use this page to specify different checkout
information for each of the lines on a requisition.
Checkout – CheckoutDistsCO.java Users can access this page from the Checkout – Edit
Distributions Lines page, to specify distribution level information
for each of the lines on the requisition.
Checkout – Update CheckoutUpdateSingleCO.java Users can access this page from the Checkout – Edit
Single Lines page to edit the information for a single line.
Checkout – Update CheckoutUpdateMultipleCO.jav Users can access this page from the Checkout – Edit
Multiple a Lines page to edit the information for multiple lines.
Approval List ApprListCO.java Users can access this page if they choose to proceed
after completing the checkout information.
Approval List - Change ApprChfCO.java Users can access this page from the Approval list
First Approver page.
Review and Submit ReviewSubmitCO.java This is the last page in the step-by-step checkout flow
before the user can submit the requisition.
Requisition ReqConfirmCO.java Users are taken to this page after the requisition
Confirmation submission process.
APPLICATION MODULES
Overview
An Application Module acts as the interface between the client and the server. It is a container that manages and provides
access to related BC4J and OA objects. Therefore, all objects that are involved in the same user transaction are grouped
into one Application Module, even if there are multiple pages in the transaction. The Application Module handles all the
events and implements all the logic on each of the pages in the transaction. Application Modules provide a logical
separation between the different process flows in the application. Therefore, a new Application Module is generally
defined for each of the transactions within the application.
Description
5
11.5.10: Oracle iProcurement Architecture Review
Requisition Management AM ReqMgmtImpl.java Responsible for managing all pages under the
Requisition Life Cycle Management flow,
including Requisition Details, Requisition Line
Details, Requisitions Summary etc.
Contractor Performance AM ContractorPerformanceAMImpl.jav Responsible for managing the pages enabling the
a customer to create and manage contractor
performance entries.
Contractor Home AM ContractorHomeAMIml.java Responsible for managing the pages under the
Contractors tab including Contractor Summary,
Contractor Advanced Search.
SERVER COMMANDS
Overview
A Server Command is a class that contains code that would normally be placed in an Application Module. The code is
extracted out into a separate class to prevent the Application Module from becoming too big, ease maintenance, facilitate
concurrent development and promote reuse (different Application Modules may be able to use the same Server Command
class). For example, a Server Command class could contain the code used to populate/query the different VOs displayed
on a particular page, or contain the code to apply changes to all the requisition lines.
Description
Every Server Command class should implement the ServerCommand interface. At runtime, a Server Command is invoked
by name. There are two methods in the RequisitionAM that are used to invoke the Server Commands by name.
6
11.5.10: Oracle iProcurement Architecture Review
args – List of parameters that are input to the Server Command
The Server Command can be invoked from the client-tier (Controller) through one of the above methods in the
Application Module. With this architecture, all the logic/events on the user interface is handled via methods in the Server
Commands, providing modularity and reuse.
The list of the Server Commands used in the requisition checkout flow, along with descriptions is as detailed below.
CheckoutLinesSvrCmd.java Checkout – Edit Lines, Implements the logic on the checkout – edit
Checkout - Update Single, lines page, the checkout Update Single Line
Checkout – Update Multiple page and the Update Multiple Lines page.
ReqAttachmentsSvrCmd.java Requisition Attachments Encapsulates all the logic for adding and
deleting attachments at the header and line
level during the checkout flow.
ReqReviewSvrCmd.java Requisition Review and Encapsulates all the logic for displaying
Submit header, line and distribution information on
the Requisition Review & Submit Page.
OneTimeLocationSvrCmd.java One Time Location Implements all the logic for adding,
displaying, editing and deleting a one-time
location for a requisition line during the
checkout process.
ReqSupplierSvrCmd.java Contractor Request Implements all the logic on the second page
7
11.5.10: Oracle iProcurement Architecture Review
ContractorShoppingCartSvrCmd.jav Contractor Shopping Cart Implements all the logic on the contractor
a shopping cart page. This includes both the
first time checkout flow as well as the assign
contractor checkout flow.
Notes
Server Commands often handle more than one task. For example, a Server Command class may handle a number of
different requests a user can make from a particular page. In this case, an argument is passed to the Server Command
class that indicates the request and then calls the appropriate method inside the Server Command class.
ENTITY OBJECTS
Overview
An Entity Object (EO) encapsulates interactions with the database related to a row in a particular table. In a typical OA
implementation, all the defaulting and validation logic associated with an entity is implemented in the corresponding
Entity Object. However, in order to facilitate concurrent development, ease maintenance and promote reuse, Helpers (as
described in the next section) are used in conjunction with one or more Entity Objects.
In order to optimize system performance, validations on Entity Objects should typically be performed when the any of the
values on an entity changes from a previously validated state. Transient member variables on the Entity Object keep track
of whether certain attributes have changed. Helpers can then check the value of this attribute and decide whether to carry
out certain validation or defaulting. These member variables will be reset after passivation, so the default values will be
set in such a way that validations will be executed after activation. The section below on Business Attribute Sets provides
some more details on this.
The list of the key Entity Objects in the iProcurement architecture is shown below.
Base EO This is a base Entity Object that all the other PorBaseEOImpl.java
Entity Objects inherit from
8
11.5.10: Oracle iProcurement Architecture Review
PO_REQUISITION_HEADERS_ALL table
and models the Requisition Header
Class Diagram
PorBaseEOImpl
ReqHeaderToReqLineAO ReqLineToReqDistAO
Business Views
Business Views are used, when a certain subset of attributes on an entity (header, line or distribution) need to be
validated, rather than the entire entity. For e.g. on the shopping cart page, since the user can only modify quantity, price
and edit/add information templates, it is premature to validate other information that the user has not yet entered such as
the delivery and the billing information. Hence, calls are only made to a subset of the Helpers as defined in the Business
View to Helper mapping, depending on the attributes displayed to the user on the page.
The following is the list of the Business Views, along with the associated Helpers and the page within the application
where it is used.
9
11.5.10: Oracle iProcurement Architecture Review
10
11.5.10: Oracle iProcurement Architecture Review
account is defined on the requisition line Entity Object with the deliver to location as one of the attributes to indicate that
if the deliver to location changes, the charge account needs to be recomputed.
The list of the key Business Attribute Sets defined, the related Entity Object and intended functionality is as defined
below.
TaxCodeBizAttrSet Determines if the tax code Requisition Line EO Vendor, Vendor, Site,
on the requisition line Deliver to location, Deliver
needs to be recomputed to Organization
11
11.5.10: Oracle iProcurement Architecture Review
The Business Attribute Sets defined above include a pre-defined set of attributes that indicate when certain logic needs to
be fired in the application. In some cases, there might be a need to extend this set to include certain other attributes based
on a custom logic. An example of this would be when a customer enables a Descriptive Flexfield (DFF) on the requisition
line and wants this attribute to drive the account generation. In other words, when a user changes the value of this DFF
attribute, the charge accounts on the distributions for the line should be redefaulted based on the new DFF value. This can
be done by extending the AccountLineBizAttrSet defined above to include the DFF attribute.
1. First, extend the Entity Object (EO) that contains your target attribute(s). Follow steps 1 to 4 in the OA
Developer’s Guide to extend the EO. Since you will be extending EOs in the BC4J package
oracle.apps.icx.por.schema.server, you need to first open this package in your project. If your target attribute is
on a requisition line, select oracle.apps.icx.por.schema.server.PoRequisitionLineEO in the “Extends Entity” field.
If your target attribute is on a requisition distribution, select
oracle.apps.icx.por.schema.server.PoReqDistributionEO instead.
2. In step 2 of the Entity Object Wizard, click the “New from Table…” button and select your target attribute(s). Hit
“OK”. Accept the defaults for the rest of the steps in the wizard.
3. In the System Navigator panel, highlight the EO you created in step 1-2. The Structures panel will list all the
attributes in the EO.
4. For each of your target attributes, highlight it in the Structures panel and click the right-mouse button and select
the “Edit” option. The Attribute Editor will come up.
5. Select Properties from the left-hand panel. If your attribute is associated with a requisition line, enter
“AccountLineBizAttrSet” in the name field and “Y” in the value field. If your attribute is associated with a
requisition distribution, enter “AccountDistBizAttrSet” in the name field and “Y” in the value field. Click “Add”,
then Hit “OK” and save the changes.
6. Once you have completed extending the Entity Objects, you need to follow the setup steps listed in the “Substitute
the Extended BC4J Object for the Parent BC4J Object” section in the OA Developer’s Guide. You need to restart
the middle-tier JVMs after these changes.
12
11.5.10: Oracle iProcurement Architecture Review
HELPERS
Overview
There are 2 categories of Helpers – Entity Object Helpers and Server Command Helpers. Entity Object Helpers contain
defaulting and validation logic for Entity Objects. Each EO Helper implements a particular interface related to the EO
(e.g. PoReqLinesAllEOHelperInterface for the Requisition Lines EO). An EO Helper can “help” more than one EO by
implementing several EO Helper interfaces. Server Command Helpers (e.g. DataMappingHelper) contain reusable
processing and validation logic that are part of a Server Command.
• Uses the Helper map to provide an instance of the Helper at run time to the corresponding Server Command that
has invoked a Helper method
• Each of the Helpers implement the CacheEnabledHelper interface to allow for caching the validated values for
the attributes that each Helper is responsible for
• Helpers invoke methods in the validation VO or execute PL/SQL to perform validations or execute business
logic
Description
Helpers are created for Entity Objects based on a logical grouping of attributes on the EO. For e.g. Project, Task,
Expenditure Type, Expenditure Org and Expenditure Item Date are all handled by the ProjectHelper since these attributes
are logically related.
13
11.5.10: Oracle iProcurement Architecture Review
When an EO is created, each of the associated EO Helpers is responsible for providing the appropriate default values.
Similarly, when an EO is validated, the validation is delegated to the Helpers. In addition to the logical grouping of
attributes within Helpers, attributes for each of the requisition Entity Objects (header, line and distribution) are grouped
into logical groupings (Business Views). There is a pre-defined set of Business Views, and each page displays one of the
pre-defined Business View. The Business View corresponding to the page is notified by the client-tier to the server-tier.
Code in the Helpers can decide whether to execute certain logic based on the Business View, as well as any other data
element the Helper has access to.
Helper Interfaces
There are 3 main Helper interfaces – one for each of the Entity Objects (header, line and distribution). Each interface
contains a number of different methods that is implemented by the Helpers implementing the interface, and implements
the defaulting and validation logic for the attributes on the entity.
The list of the interfaces along with the key methods in them are as listed below.
PoRequisitionHeaderEOHelper
defaultFromCreate Method called when the first line is added to a new requisition.
This defaults the values on the attributes on the requisition
header.
PoRequisitionLineEOHelper
defaultFromDuplicate Method called when a requisition line is copied on the Edit Lines
14
11.5.10: Oracle iProcurement Architecture Review
PoReqDistributionEOHelper
defaultFromDuplicate Method called when a requisition line is copied on the Edit Lines
page to create a new line on the same requisition.
Using this architecture, existing Helpers can be extended when additional customer specific defaulting or validation logic
needs to be added. This would supplement any logic that’s already implemented as part of the application.
As an example, lets consider the case when a customer desires to extend the defaulting logic for the requester information
on the requisition line for a new requisition. The following are the steps that would need to be done in order to extend the
RequesterHelper and supplement the defaulting logic for the requester on the requisition line.
The first step in the process is to determine the name of the Helper that would need to be extended. This would depend on
the functionality that needs to be implemented and the attributes and the entity that this would affect. So, in the example
above, the attribute of interest in the requester information on the requisition line. The defaulting logic for the Requester
is implemented in the RequesterHelper and therefore, this would be the Helper that needs to be extended.
Once the Helper to be extended has been decided, the next step would be to come up with an appropriate name for the
15
11.5.10: Oracle iProcurement Architecture Review
new Helper class that needs to be created. Since this class would extend the Helper class selected above, its reasonable to
pick a name that indicates the Helper to which it is associated. In the example above, the new Helper class can be named
as MyRequesterHelper (The corresponding file name is MyRequesterHelper.java). The new Helper class should also be
created in the same package as the Helper class it extends. So, MyRequesterHelper would be created in the
oracle.apps.icx.por.schema.server package.
package oracle.apps.icx.por.schema.server;
Once the new Helper class has been created, the next step would be to determine the method that needs to be extended
from the parent Helper class. In the example above, since the defaulting logic for the requester needs to be extended in
case of a new requisition, the defaultInternal() method on the RequesterHelper should be extended to add any new
logic. Its important to note that the method in the new class should call super.defaultInternal() method first, so
that all the standard defaulting logic for the requester gets executed.
package oracle.apps.icx.por.schema.server;
super.defaultInternal(txn,linesEO);
The architecture uses a Helper mapping class to determine which Helper to call when the requisition is being created, for
defaulting and validating the attributes on the requisition header, line and distribution. Since a new Helper class is created
in Step 3, the Helper class map would also need to be extended to include this Helper class.
Package oracle.apps.icx.por.common;
16
11.5.10: Oracle iProcurement Architecture Review
public String getClass(String name)
if (“RequesterHelper”.equals(name))
return "oracle.apps.icx.por.schema.server.MyRequesterHelper";
else
return (String)s_classNames.get(name);
Once the new Helper class map has been defined, a call needs to be made to this Helper class map from the
RequisitionAM, so that all the right Helpers get invoked during the requisition creation process.
A new property has to be defined on the AM that allows the architecture to decide the class map that needs to be loaded
as part of the AM. The entry in the bold in the XML file below helps achieve that.
<AppModule>
Name="RequisitionAM"
ComponentClass="oracle.apps.icx.por.req.server.RequisitionAMImpl"
LoadComponentsLazily="true" >
<Properties>
</Properties>
</AppModule>
The View Objects and View Rows in iProcurement follow the basic OAF architecture and hence, no further details are
provided in this document.
17
11.5.10: Oracle iProcurement Architecture Review
Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.
Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
www.oracle.com
Oracle is a registered trademark of Oracle Corporation. Various
product and service names referenced herein may be trademarks
of Oracle Corporation. All other product and service names
mentioned may be trademarks of their respective owners.
Copyright © 2003 Oracle Corporation
All rights reserved.
18