Beruflich Dokumente
Kultur Dokumente
Oracle Corporation
Web ADI Integrator Developers
Guide
Approvals:
John Richardson
Brett Hooker
Change Record
6
Contributors
Document Reference
ii
Company Confidential - For internal use only
Reviewers
Name Position
Distribution
iii
Company Confidential - For internal use only
Contents
Glossary.................................................................................................................................... 7
1. Overview ................................................................................................................. 10
1.1. Functionality .................................................................................................... 10
1.2. Integrator Development ................................................................................. 10
2. Defining an Integrator ........................................................................................... 12
2.2 Associate Form Function(s) with Integrator ........................................................ 12
To Delete an Association .............................................................................................. 13
To Update an Association ............................................................................................ 13
3. Adding Interfaces ................................................................................................... 15
3.1. Creating a PL/SQL API Interface ................................................................. 15
3.2. Creating a Table Interface .............................................................................. 19
3.3. Uploading to Multiple Interface Tables or APIs ......................................... 20
4. Updating Interface Columns/API Parameters .................................................. 21
4.1. Create Interface Columns............................................................................... 21
4.2. Interface Columns Concepts.......................................................................... 23
5. Creating Components ............................................................................................ 33
5.1. Creating Table Validated Components ........................................................ 33
5.2. Creating Date Picker Components................................................................ 37
5.3. Creating JAVA Validated Components ....................................................... 40
SQL Java Class ............................................................................................................... 41
Validator Java Class ...................................................................................................... 44
Implementing a Group Validator Java Class............................................................. 48
Component Java Class .................................................................................................. 50
Implementing the Component Java Class.................................................................. 51
Metadata for Java Validation .............................................................................................. 55
BNE Parameter Definition Tables ............................................................................... 55
BNE Parameter List Tables........................................................................................... 56
BNE Parameter List Items Table.................................................................................. 57
BNE Component Tables................................................................................................ 57
BNE Interface Column(s) Tables ................................................................................. 58
6. Defining an Importer ............................................................................................. 61
6.1. Indicate Importer Type................................................................................... 61
6.2. Define Master Parameter List ........................................................................ 62
6.3. Enter Metadata for Steps in Master List....................................................... 64
iv
Company Confidential - For internal use only
7. Defining Upload Parameters ................................................................................ 78
7.1. Upload Parameters Screen ............................................................................. 78
7.2. Create Upload Parameter List ....................................................................... 78
8. Creating Content .................................................................................................... 81
8.1. Stored SQL........................................................................................................ 81
8.2. Text File............................................................................................................. 83
8.3. Java .................................................................................................................... 84
9. Reporting Only Documents .................................................................................. 86
9.1. Reporting only with Data Entry Interfaces.................................................. 86
9.2. Reporting only Interfaces, Mappings and Layouts .................................... 86
10. Creating Layouts and Mappings.......................................................................... 87
10.1. Creating Layouts ............................................................................................. 87
10.2. Creating Mappings ......................................................................................... 89
11. Calling the Create Doc Page Flow........................................................................ 92
11.1. Available Parameters...................................................................................... 92
11.2. Sending Parameters to BneApplicaitonService........................................... 93
APPENDIX A Parameter UI............................................................................................. 97
Accessing Parameter UI................................................................................................ 97
Defining Parameter Lists .............................................................................................. 97
Defining Parameter List Items ..................................................................................... 97
Defining a Parameter Definition ................................................................................. 97
Associating a Parameter Definition to a Parameter.................................................. 98
Testing Your Parameter List ........................................................................................ 98
APPENDIX B Shipping Your Integrator......................................................................... 99
Applications 11i ............................................................................................................. 99
Applications 12 .............................................................................................................. 99
APPENDIX C - Sample Code............................................................................................ 102
Sample SQL Class - BneOAPeriodNameSQL (GL Journals Period Name
LOV/Validator) ........................................................................................................... 102
Sample Validator Class - BneOAPeriodNameValidator (GL Journals Period
Name LOV/Validator) ............................................................................................... 104
Sample Component Class - BneOAPeriodNameComponent (GL Journals Period
Name LOV) .................................................................................................................. 114
Sample Metadata for the Period Name Java Validation ........................................ 120
BNE Parameter List Sample Metadata for the Period Name Validator/LOV . 123
BNE Parameter List Items Sample Metadata for the Period Name
Validator/LOV ............................................................................................................ 123
BNE Component Sample Metadata for the Period Name Validator/LOV...... 124
BNE Interface Column(s) Sample Metadata for the Period Name
Validator/LOV ............................................................................................................ 125
BNE Interface Column(s) Sample Group Validator (Reversal Group Validator)125
APPENDIX D Security .................................................................................................... 127
Examples - Download................................................................................................. 128
Decorator for BneStoredSQL for securing parameters........................................... 128
Examples Upload / LOV......................................................................................... 130
Security Contexts ......................................................................................................... 130
Input Filter .................................................................................................................... 131
v
Company Confidential - For internal use only
General Coding Considerations ................................................................................ 131
vi
Company Confidential - For internal use only
Glossary
Asynchronous Call
An asynchronous call occurs where the uploading of data to interface tables is a separate
process from importing interfaced table data to Oracle Applications (i.e. they dont happen at
the same time).
When an upload occurs, an import program is called and the request id is returned to the user.
Oracle Applications proceeds to run the import program in the background and it is up to the
user to manually check whether the import program was successful in its processing. This
means the submission of the upload and the completion of the import program are not
synchronized, hence the usage of the asynchronous terminology.
Client
Some software requiring a function to be performed by another piece of software (the Server).
Clients pass parameters to Servers
Content
This is the information that will be downloaded into the Viewer. Multiple Contents can be
defined for a single Content Class. The Content that is passed to or selected in the Create
Document page flow determines the Content Class that will be used to derive the Content data.
Content Column
A name defined in metadata to represent a column that exists in the Content. Users map the
Content Columns to interface columns/API parameters so that data is downloaded to the
appropriate fields in the document.
Content Class
This is the java code containing the business and processing rules that can be plugged into
the Web ADI Download architecture. This code processes the parameters that are passed to
Web ADI, to retrieve information from the selected Content.
Integrator
An Integrator is a Web ADI term used to encapsulate all of the information required to move
data to/from a desktop application into Oracle Applications. An Integrator definition may
include information about open interface tables, validation, business rules, and data that can be
downloaded.
Integrator Developer
The Integrator Developer is a developer who defines the metadata required within Web ADI.
The metadata includes: the Integrator, table/view definitions, Layouts, Mappings, SQL
statements and parameters. The Integrator Developer will usually be a System Administrator
or a user with a more advanced understanding of Web ADI, and knowledge of the tables and
business rules associated with the product being integrated with.
Interface
Interface is a Web ADI term for the column definitions from a particular API or Interface
table/view to be used for uploading data into the database. Multiple Interfaces can be defined
for a single Integrator.
Language
This is the Language in which a document will be generated, and in which all interaction within
the document will be conducted.
Layout
A Layout tells Web ADI which columns will be displayed in the Desktop Application document
and how those columns will be displayed, including formatting. Web ADI provides a set of
screens that users and Integrator Developers can use to create their own Layouts. Integrator
Developers are able to provide Layouts as seed data.
Mapping
A Mapping is defined to link the columns from the Content to the columns in a table/API
Interface. For example, the columns in a SQL query that are downloaded into an MS Excel
spreadsheet are mapped to the columns in an open interface table into which the downloaded
information will be uploaded.
Parameter
A parameter is a name / value pair used to pass information between a client and a server. The
parameter may be known by a textural (string) name, or a position in a list. The parameter
value must have a data type, which one is known and understood by the client and server.
There is generally a description available for the parameter value that is displayed to the user.
Example: param name = bne:integrator, datatype = string, param value =
231:JOURNALS_11I with description Journals for Applications 11i.
8
Company Confidential - For internal use only
Server
Some software that does a job for a Client. Servers receive parameters from Clients.
Static Parameter
A static parameter is a parameter completely defined by metadata stored in the Web ADI
repository. A static parameter can be read and a value obtained immediately either by a default
value stored against it, or a specific stored value.
Synchronous Call
A synchronous call occurs where the uploading of data to interface tables and import to Oracle
Applications occur in one process. A synchronous call entails submitting the import program,
waiting for the import program to finish running, determining the success or failure of the
import and returning these details to the user. In this scenario, the user will not have to
manually check whether the import program completed successfully.
Viewer
A Viewer is a Web ADI term for the desktop application in which a document will be
generated.
9
Company Confidential - For internal use only
1. Overview
1.1. Functionality
Web ADI allows Oracle Applications developers to rapidly create desktop interfaces to their own Applications.
They can bring Oracle Application data and business rules to a desktop application such as Excel to give users
more flexibility in entering, modifying and modeling data.
Create a formatted document on the desktop containing application specific fields for data entry.
Validate fields in the document and provide instant feedback (error/confirmation messages) during the
upload process.
All of this is done is done over the Web; no client install is necessary. Users need only IE and a viewer installed
on their PCs. The viewer currently supported is Excel.
The above functionality is applied to your application through the development of an Integrator. Creating an
Integrator involves updating Web ADI tables. This metadata is used By Web ADI to capture the business rules of
your product so that they may be enforced on the desktop. Most of the metadata is created through PL/SQL
packages and HTML UI. There may be cases when tables are updated through SQL Plus.
To enable upload, Integrator Developers must identify the tables or APIs a document will point to. They then
describe the columns/parameters of those tables/APIs and how they should be validated. Integrator developers
may also describe the program they use to import data from interface tables to application base tables. Web ADI
will look at this metadata to automatically call the import program after it has successfully uploaded data to the
interface. Parameters shown to users that govern the upload process can also be defined. In addition, users may
want to download information into the document, edit then upload to Oracle Applications. To enable download,
metadata on what will be downloaded is entered. Information on how the downloaded data is mapped to
columns in the document is also created. Some Integrators my only allow users to download information to a
document for analysis, and not provide upload.
Define an Integrator
Define Interfaces
Create Components
Define Importer
10
Company Confidential - For internal use only
Defining Upload Parameters
Creating Content(s)
This document describes these steps in detail and provides information on how Web ADI can be invoked.
11
Company Confidential - For internal use only
2. Defining an Integrator
A PL/SQL script is available for Integrator Developers to quickly create the core metadata of an Integrator. This
includes a data-source type, and an Integrator Definition.
Call the following PL/SQL package to create the core metadata for your Integrator:
BNE_INTEGRATOR_UTILS.CREATE_INTEGRATOR
(P_APPLICATION_ID IN NUMBER,
P_OBJECT_CODE IN VARCHAR2,
P_INTEGRATOR_USER_NAME IN VARCHAR2,
P_LANGUAGE IN VARCHAR2,
P_SOURCE_LANGUAGE IN VARCHAR2,
P_USER_ID IN NUMBER,
P_INTEGRATOR_CODE OUT VARCHAR2);
Parameter Description
P_APPLICATION_ID The identifier for an application. An example would be 101 for General
Ledger
P_OBJECT_CODE A string of 20 chars or less. The only valid characters are: Uppercase
'A'..'Z', '0'..'9' and '_'. This string must be unique within the application
ID. The API will use this code to generate the P_INTEGRATOR_CODE.
P_INTEGRATOR_CODE = P_OBJECT_CODE + _INTG
P_INTEGRATOR_USER_NAME The Integrator name displayed to users on the Integrator page in the
Create Document Page Flow. The standard format for Integrator name is
<Product Name> - <Module/Function Name>. An example would be
General Ledger - Journals.
P_LANGUAGE The language the User Integrator Name will be stored against
P_SOURCE_LANGUAGE The Language that the User Integrator Name will be translated from
P_USER_ID Oracle Applications user ID
P_INTEGRATOR_CODE This is generated by the API. It uniquely identifies your Integrator within
your application and can be used when calling the Web ADI service.
BNE_SECURITY_UTILS_PKG.ADD_OBJECT_RULES
( P_APPLICATION_ID in NUMBER,
P_OBJECT_CODE in VARCHAR2,
P_OBJECT_TYPE in VARCHAR2,
P_SECURITY_CODE in VARCHAR2,
P_SECURITY_TYPE in VARCHAR2,
P_SECURITY_VALUE in VARCHAR2,
P_USER_ID in NUMBER);
Parameter Description
12
Company Confidential - For internal use only
Parameter Description
To Delete an Association
Call the following Package:
BNE_SECURITY_UTILS_PKG.DELETE_OBJECT_RULES
( P_OBJECT_APP_ID in NUMBER,
P_OBJECT_CODE in VARCHAR2,
P_OBJECT_TYPE in VARCHAR2,
P_SECURITY_APP_ID in NUMBER,
P_SECURITY_CODE in VARCHAR2);
Parameter Description
To Update an Association
Call the following Package:
BNE_SECURITY_UTILS_PKG.UPDATE_OBJECT_RULES
( P_OBJECT_APP_ID in NUMBER,
P_OBJECT_CODE in VARCHAR2,
P_OBJECT_TYPE in VARCHAR2,
P_SECURITY_APP_ID in NUMBER,
13
Company Confidential - For internal use only
P_SECURITY_CODE in VARCHAR2,
P_SECURITY_TYPE in VARCHAR2,
P_SECURITY_VALUE in VARCHAR2,
P_USER_ID in NUMBER);
Parameter Description
14
Company Confidential - For internal use only
3. Adding Interfaces
A PL/SQL API is provided to create Interfaces for an Integrator. An Interface identifies a database table or PL/SQL
API that you will be populating with Web ADI. More than one Interface can be defined for an Integrator; the API
must be run each time an Interface is to be added.
It is possible to create an Interface that does not provide upload, but only allows users to download data into the
document for reporting purposes. If this is what is required, skip to section 8 and create a Content for your
Integrator, then run the API described in section 9.2.
Creating an Interface for an API involves calling an API that will generate a parameter list. This list is then
updated to identify all the parameters in the API and their Attributes. Lastly, the parameters that will be
updates from the desktop will be related to records created in BNE_INTERFACE_COLS_B; this will enable
users to create layouts that include the API parameters defined in the list.
3.1.1. Run the following PL/SQL package to create an Interface for a PL/SQL API:
BNE_INTEGRATOR_UTILS.CREATE_INTERFACE_FOR_API
(P_APPLICATION_ID IN NUMBER,
P_OBJECT_CODE IN VARCHAR2,
P_INTEGRATOR_CODE IN VARCHAR2,
P_API_PACKAGE_NAME IN VARCHAR2,
P_API_PROCEDURE_NAME IN VARCHAR2,
P_INTERFACE_USER_NAME IN VARCHAR2,
P_PARAM_LIST_NAME IN VARCHAR2,
P_API_TYPE IN VARCHAR2,
P_API_RETURN_TYPE IN VARCHAR2 DEFAULT NULL,
P_UPLOAD_TYPE IN NUMBER,
P_LANGUAGE IN VARCHAR2,
P_SOURCE_LANG IN VARCHAR2,
P_USER_ID IN NUMBER,
P_PARAM_LIST_CODE OUT VARCHAR2,
P_INTERFACE_CODE OUT VARCHAR2);
Parameter Description
P_APPLICATION_ID The identifier for an application. An example would be 101 for General
Ledger
P_OBJECT_CODE A string of 20 chars or less. The only valid characters are: Uppercase
'A'..'Z', '0'..'9' and '_'. This string must be unique within the application
ID.
P_API_PACKAGE_NAME The package name that contains your PL/SQL API procedure.
P_LANGUAGE The language the User Integrator Name will be stored against
P_SOURCE_LANGUAGE The Language that the User Integrator Name will be translated from
P_USER_ID Oracle Applications user ID
P_INTEGRATOR_CODE Set to the Integrator Code that was created in section 2.
Query BNE_INTEGRATORS_TL to look up the code of any
Integrator.
15
Company Confidential - For internal use only
Parameter Description
3.1.2.2. Press the Edit button next to the Attributes label in the Define Parameter list screen. Enter the
details about the function name and return type for the PL/SQL function. When you are
finished, press Apply and return to the Define Parameter List screen.
Example :
16
Company Confidential - For internal use only
3.1.3. Use the Add Another Row button to identify all the parameters that exist in your API to the
parameter list. A parameter must be added to the list for every PL/SQL function/parameter
declaration and PL/SQL parameter for the function call. In addition, the order in which these
parameters are defined in the parameter list must be the exact order in which they are defined in the
PL/SQL API
3.1.3.1. After pressing Add Another Row, you will be presented with the Define Parameter
Screen. Use this screen to enter the details for each parameter you add the list.
17
Company Confidential - For internal use only
Example:
3.1.3.2. Identify attributes for each parameter you define in the list. User the edit button next to the
Attributes label (see above) to access the attributes for each parameter you define. If you have
default values defined within your API definition for a particular parameter, these default values
must also be set in Attribute 5. For example, if you have NULL being the default value for row_id
in your API definition, you must also enter NULL in Attribute 5 when identifying this parameter
in the parameter list.
Example:
18
Company Confidential - For internal use only
3.1.4. Create records in BNE_INTERFACE_COLS_B for every PL/SQL API parameter you wish to pass
values to from a document on the desktop. Relate a parameter identified in the parameter list with a
record in BNE_INTERFACE_COLS_B by entering the parameters sequence number in
BNE_INTERFACE_COLS_B.UPLOAD_PARAM_LIST_ITEM_NUM. See Updating Interface
Columns/API Parameters for more information on creating records in this table.
BNE_INTEGRATOR_UTILS. CREATE_INTERFACE_FOR_TABLE
(P_APPLICATION_ID IN NUMBER,
P_OBJECT_CODE IN VARCHAR2,
P_INTEGRATOR_CODE IN VARCHAR2,
P_INTERFACE_TABLE_NAME IN VARCHAR2,
P_INTERFACE_USER_NAME IN VARCHAR2,
P_LANGUAGE IN VARCHAR2,
P_SOURCE_LANG IN VARCHAR2,
P_USER_ID IN NUMBER,
P_INTERFACE_CODE OUT NOCOPY VARCHAR2);
Parameter Description
P_APPLICATION_ID The identifier for an application. An example would be 101 for General
Ledger
P_OBJECT_CODE A string of 20 chars or less. The only valid characters are: Uppercase
'A'..'Z', '0'..'9' and '_'. This string must be unique within the application
ID. This string will be used to generate P_INTERFACE_CODE.
P_INTERFACE_CODE = P_OBJECT_CODE + _INTF.
P_INTEGRATOR_CODE Set to the Integrator code the Interface will be defined under
P_LANGUAGE The language the User Integrator Name will be stored against
P_SOURCE_LANGUAGE The Language that the User Integrator Name will be translated from
P_USER_ID Oracle Applications user ID
P_INTERFACE_CODE This is generated by the API. It uniquely identifies your Integrator within
your application and can be used when calling the Web ADI service.
19
Company Confidential - For internal use only
3.2.2. Create records in BNE_INTERFACE_COLS_B for every column in your table. Not the
INTERFACE_CODE created in 3.2.1. This will be needed to create your interface columns. See
Updating Interface Columns/API Parameters for more information on this step.
To define layouts that upload to more than one Interface table or API, you simply define more than one
Interface for an Integrator. The list of fields a user has to choose from when defining their layouts will
contain all of the Interfaces you have defined. After you have defined your Interfaces, update
BNE_INTERFACES.UPLOAD_ORDER with a numeric value for each Interface to indicate the order in
which each Interface is updated when users upload their documents. This will be useful when uploading
to APIs since APIs must often be called in a particular order.
20
Company Confidential - For internal use only
4. Updating Interface Columns/API Parameters
The columns/parameters of the Interface tables/APIs must be identified in metadata. The metadata described in this
section facilitates the core Web ADI services including upload, validation, defining Layouts, defining Mappings, and
list of values.
Metadata must be entered for evey API Parameter or table column that exists in your Interface. This
information is stored in BNE_ITNERFACE_COLS_B (TL). Follow the instructions below to enter identify
your columns.
4.1.1. An Interface Columns Integrator is available for you to quickly create/edit interface column
metadata.
4.1.1.1. You must run the following script if you do not see a Web ADI Interface Columns
Integrator on the Integrator page of the Create Document Page flow.
update bne_integrators_b
4.1.1.2. To quickly create interface columns using Excel, enter the Create Document Page flow
and select Web ADI Interface Columns Integrator and the All Columns layout. The APIs you
21
Company Confidential - For internal use only
called in the previous section may have already created many of these records for you. If you
want to download records already created for your Interface, select Interface Columns for the
Content and enter the Interface Code you created in the previous section 3. Records will be
downloaded into Excel, where they can be changed/created and uploaded.
4.1.2. Below is a list of fields that will appear in the spreadsheet and their descriptions. * = Required
FIELD_SIZE (Size) The size of the column in the interface table or character length for a parameter.
Web ADI uses this value to validate data in the document.
DEFAULT_TYPE Indicates the form of the DEFAULT_VALUE. Valid values for this field are
SQL, ENVIRONMENT, CONSTANT, and TABLELOOKUP. CONSTANT uses
the actual value in DEFAULT_VALUE for this field upon upload.
ENVIRONMENT Indicates an environmental variable defined in
DEFAULT_VALUE . SQL indicates a SQL statement exists in DEFAULT_VALUE
that will be used to determine the value to be used for this field during upload.
TABLELOOKUP will default the value from another column. Default values are
not automatically inserted into the document when it is created, they are derived
at upload time.
DEFAULT_VALUE Default value to be used for the field when it uploaded. This value will not be
automatically inserted into the document when it is created, but will be used for
upload if no value exists for it in the document; i.e., The value in the document
will be uploaded if one exists, and the default value will be ignored.
SEGMENT_NUMBER Indicate the position within the group.
GROUP_NAME Indicates the group the column/parameter is assigned to
OA_FLEX_CODE (Flex Code) Flexfield structure identifier.
OA_CONCAT_FLEX (Concat Flex) Concatenates the value entered for this column/parameter into one cell in a
spreadsheet.
READ_ONLY Y/N. If YES, then the user cant change this value and it is placed in the context
section of the document.
VAL_TYPE (Validation Type) Indicates the Validation Type. Valid values are DESCFLEX,
DESCFLEXCONTEXT, DESCFLEXSEG, GROUP, JAVA, KEYFLEX,
KEYFLEXSEG, and TABLE. This column is left null if no validation other than
validating the DATA_TYPE/FIELD_SIZE /NOT_NULL_FLAG is to be done.
22
Company Confidential - For internal use only
Column (Field) Name Description
VAL_ID_COL (Val id ID) Column to query when Web ADI constructs its SQL Query. This will be the
actual value inserted into the Interface Table
VAL_MEAN_COL (Valid This is the column that contains the user value for values in VAL_ID_COL. These
Meaning) are the values shown in the LOV shown in the worksheet.
VAL_DESC_COL (Valid Desc) Column that contains the description for values in VAL_ID_COL. These values
are shown in the description section of the LOV.
VAL_OBJ_NAME (Valid Object) Table or Java class that is called to validate values in the sheet. If VALTYPE =
TABLE, then the name of the table to query is placed in this column (e.g.
FND_LOOKUPS). If VALTYPE =JAVA, then specify the Java class to call when
validating the column (e.g.
oracle.apps.bne.integrator.validators.BneAccountingFlexValidator).
VAL_ADDL_W_C (Valid Where) Enter an additional Where Clause to add to a Table Validated column.
DATA_TYPE Three values can be entered in this column. 1 = value in database/API must be a
number; 2 = value in the database/API must be varchar; 3 = value in the
database/API must be a date. Web ADI will use this value to validate data in the
document.
NOT_NULL_FLAG Indicates that column in the DB or parameter for the API cannot be null. Web
ADI uses this value to validate data in the document..
VAL_COMPONENT_APP_ID Application ID of component to be called in BNE_COMPONENTS
(Valid Component)
VAL_COMPONENT_CODE Name of Component from BNE_COMPONENTS that will be called to retrieve
the LOV for this field. TABLE and JAVA VAL_TYPES require this field to have a
value if an LOV is to be retrieved. See Creating Components for more details.
SUMMARY_FLAG Indicates if value for this column/parameter can be summed up in the document.
MAPPING_ENABLED_FLAG* Indicates whether a column/parameter can be included in a Mapping so that it
can be mapped to a content column. (Y/N)
Prompt Left Column header for field if in the Header region of the document. This value
must be entered if the column header is to appear in the document and if the
column is to be displayed in the Mapping and Layout UI.
Prompt Above Column header for field if in the Lines region of the document. This value must
be entered if the column header is to appear in the document and if the column is
to be displayed in the Mapping and Layout UI.
User Hint Text Text to appear in the hint section for the column. This is the area between the
data entry cells and the Header.
Language Language that will be entered in the TL Table
SOURCE_LANGUAGE Language prompts will be translated from
OA_FLEX_NUM (Flex Number) Flexfield structure identifier.
OA_FLEX_APPLICATION_ID Flexfield structure identifier.
(Flex Application)
DISPLAY_ORDER Default order in which the columns/parameters are displayed in the document
EXPANDED_SQL_QUERY For expanded columns. This is the query that will be run to return the number of
periods to be displayed in the worksheet.
(User ID) ID that will be used to populate CREATED_BY and LAST_UPDATED_BY
Use the following columns to use a SQL statement for validation during upload:
23
Company Confidential - For internal use only
VAL_ADDL_WC: Enter an additional where clause. Tokens can be used when forming the where
clause for your query:
o Language: $ENV$.LANG
Use these columns if you want to provide LOVs that use the above SQL statement:
VAL_MEAN_COL (optional): If entered, values in this column will be displayed to users in the LOV.
These meaning values will be entered into the document; ADI will translate them to their
corresponding ID values during the upload process.
Column Value
VAL_OBJ_NAME FND_CURRENCIES
VAL_ID_COL CURRENCY_CODE
VAL_ADDL_WC ENABLED_FLAG = 'Y' AND CURRENCY_FLAG = 'Y' AND
TRUNC(NVL(START_DATE_ACTIVE, SYSDATE)) <= TRUNC(SYSDATE) AND
TRUNC(NVL(END_DATE_ACTIVE, SYSDATE)) >= TRUNC(SYSDATE) OR
CURRENCY_CODE = 'STAT'
VAL_COMPONENT_ OA_CURRENCY_CODE
CODE
VAL_COMPONENT_ 231
APPID
Indicate a field will use Java Validation by entering JAVA in VAL_TYPE. Enter the class name to be used for
validation during the upload process in VAL_OBJ_NAME. If a LOV is to be provided, enter the key to the
Component that will be used to retrieve the LOV in VAL_COMPONENT_CODE.
24
Company Confidential - For internal use only
columns at once. This is done when validation involves values in different columns being dependent on one
another. It is also done to pool segments having the same validation under a parent whose record defines how
validation will be performed for each, rather than entering validation information for all the child records.
However, when Group Validation is complete, validation on individual fields is run. If one of the records has a
different VAL_OBJ_NAME, that piece of validation code will be run for the field in addition to the group
validation. Steps to set up Group Validation:
Create a parent record. It does not appear in the sheet, nor is uploaded. Identify the field as a parent
by inserting GROUP for VAL_TYPE.
Assign the dependent fields and the parent to the same group.
Enter the Java class to perform the group validation in the parents VAL_OBJECT_NAME column.
A simple example of an instance to use group validation is the entered debit and credit columns in the GL
Journals Integrator (GL_INTERFACE table). Validation on each field is dependent on the value in the other. An
example of one business rule is that the values in ENTERED_DR and ENTERED_CR must not both be null.
ENTERED_DR Y ENTERED 1
ENTERED_CR Y ENTERED 1
ENTERED_PARENT N ENTERED GROUP 2 oracle.apps.bne.validat
ors.enterDebitCreditval
idator
A parent field must be created to capture values for group validation. ENTERED_PARENT is identified as the
parent of the group by inserting GROUP for VAL_TYPE. It does not exist in the interface table, nor will it
appear in the sheet for editing. It merely acts as a placeholder for validation; the Java class to perform the Group
Validation is assigned to it in VAL_OBJECT_NAME. All three fields are assigned to the ENTERED group.
Note: Remember, validation can be run on individual columns in addition to them being validated as part of a
group.
An example where Group Validation is used in conjunction with validation done for individual members of the
group is Reference7 and Reference 8 (Reverse Journal, Reversal Period) in the GL Journals Integrator. Group
validation is used to verify that a period is entered when Reference7 is Y. In addition to this check,
REFERENCE7 TABLE validated and REFERENCE8 is JAVA validated.
Just as in the last example, a parent is created and assigned to a group with the dependent fields. This field will
not be uploaded, nor will it be displayed to users. The Java class to perform the group validation is assigned to
the parent in VAL_OBJ_NAME. In addition to being Group Validated, REFERENCE7 is being TABLE validated
against FND_LOOKUPS (VAL_ID_COL and VAL_ADDL_WC not shown). REFERENCE8 is being JAVA
validated with the pervalidator class.
25
Company Confidential - For internal use only
4.5. Key Flexfield Validation/LOV Retrieval
Web ADI supports List of Values and the validation of Key Flexfields. Group Validation is used to accomplish
this. The following is done to enable Key Flexfield validation/LOV:
These fields are not displayed in the spreadsheet but exist in the Table/API. They are not
displayed because Web ADI does not know what KFF segments from the interface table to
display when creating the document.
Set INTERFACE_COL_TYPE = 2 since this field does not exist in the interface table.
Set DISPLAY_FLAG = Y since this field will be selected in the mapping UI when the user
wants the key flexfield to be included in the worksheet.
Enter the code that is used to retrieve the Key Flexfield structure in OA_FLEX_CODE.
Enter N in OA_CONCAT_FLEX. The segments for Key Flexfields are kept in separate
columns in the document.
2. COMPONENT_CODE: OA_FLEX
3. COMPONENT_JAVA_CLASS:
oracle.apps.bne.integrator.component.BneOAFlexComponent
Example:
26
Company Confidential - For internal use only
INTERFACE_COL DISPLAYED_ GROUP VAL_TYPE INTERFACE OA_FLEX OA_CONCAT_ VAL_OBJ_NA
_NAME FLAG _COL_TYPE _CODE FLEX ME
Enter a new GROUP_NAME for the parent field (youll later assign the segments to this
group).
Enter the code that is used to retrieve the Key Flexfield structure in OA_FLEX_CODE.
Enter N in OA_CONCAT_FLEX. The segments for Key Flexfields are kept in separate
columns in the document.
Insert Record into BNE_COMPONENTS_B if one does not already exist for your product
ID:
2. COMPONENT_CODE: OA_FLEX
3. COMPONENT_JAVA_CLASS:
oracle.apps.bne.integrator.component.BneOAFlexComponent
27
Company Confidential - For internal use only
Indicate Key Flexfield segments by entering KEYFLEXIDSEG in VAL_TYPE.
Set DISPLAY_FLAG = N. These fields are not displayed in the mapping UI.
Set INTERFACE_COL_TYPE = 2 since these fields do not exist in the interface table or API.
Assign the segments to a the same group the parent segment belongs to.
Example:
Set DISPLAY_FLAG to N for all segments. This is because Web ADI does not know what
DFF segments to display when the sheet is created. The Flexfield structure is returned once
the user enters a context value
Add the DFF segments to a group by entering a meaningful name for the group in the
Group Name field.
4.7.2. Create a parent record for the group. It will be visible in the document, but does not exist in the
table/API
Set DISPLAY_FLAG to Y.
Set INTERFACE_COL_TYPE to 2.
Set OA_FLEX_CODE to the code that is used uniquely identify the Key DFF structure.
28
Company Confidential - For internal use only
Enter Y for OA_CONCAT_FLEX. The values for all the DFF segments will be
concatenated into the context column in the document.
Enter DESCFLEX for VAL_TYPE. This indicates that this field is the parent of its DFF
group.
2. COMPONENT_CODE: OA_FLEX
3. COMPONENT_JAVA_CLASS:
oracle.apps.bne.integrator.component.BneOAFlexComponent
4.7.3. Create a context field for the Descriptive Flexfield group. This context segment captures a value
that is used to determine the DFF structure is needed. The Context column is visible in the
document and exists in the interface table.
Enter Y for DISPLAY_FLAG. This field must be available to allow the user to enter a value
to retrieve the DFF structure.
Enter DESCFLEXCONTEXT for VAL_TYPE. This value indicated that this field is the
context segment for the group.
2. COMPONENT_CODE: OA_FLEX
3. COMPONENT_JAVA_CLASS:
oracle.apps.bne.integrator.component.BneOAFlexComponent
Enter OA_FLEX in VAL_COMPONENT_CODE. This will enable the LOV for the context
field.
29
Company Confidential - For internal use only
Example:
Y N TABLELOOKUP $table$.InterfaceName.InterfaceColName
Default values can be stored in metadata. Alternatively, SQL statements, environmental variables, and Java code
can all be used to generate default values. DEFAULT_TYPE describes the value in DEFAULT_VALUE. This
column has four possible values:
SQL: DEFAULT_VALUE is a SQL statement to be run to derive the default value in the document.
CONSTANT: DEFAULT_VALUE itself will be inserted into the document as a default value.
JAVA: DEFAUTL_VALUE contains a Java class that will be run to generate a default value.
30
Company Confidential - For internal use only
4.10.1. Use the Web ADI Interface Cols Integrator to identify each column in the interface table that
could possibly exist in the document.
4.10.1.4. Type = 1
4.10.1.5. Display = N
4.10.1.6. Set the SEGMENT_NUMBER sequentially to indicate the order that the columns are to
be displayed in the document. This number is also used to match the column name
returned from BNE_EXPANDED_COLS_SQL with a column in the document.
4.10.2. Create one record in the spreadsheet to be the Parent segment of the interface columns. This is
the row that will be selectable in the LAYOUTS screen.
4.10.4.1.1. Define a SQL statement that returns the Group column names and Segment Number
reference. This statement should return a result set of 2 fields. The first will be interpreted
as the Column name visible to the user. The second will be used to link with the segment
number within the Group. This allows Web ADI to link a name with an interface column.
Note that bind variables can be used so the SQL statement can be edited at run-time.
Example:
4.10.4.1.2. When the create doc service is called with the layout that contains the parent
segment. Web ADI will run the SQL statement above to determine what segments in the
group will appear in the spreadsheet. In the example above, the values for the
PERIODFROM PERIODTO parameters would be passed in the http request when the Web
ADI service is called at run-time. See calling the Create Doc Page Flow for more information
on calling the Web ADI service.
31
Company Confidential - For internal use only
32
Company Confidential - For internal use only
5. Creating Components
A component is an object defined in metadata that provides a list of values for a field in a document. They are the
values specified in VAL_COMPONENT_APP_ID and VAL_COMPONENT_CODE in BNE_INTERFACE_COLS_B.
Attention: You must make sure that the code you plug into the Web ADI SDK is
functionally secure. Users must be prevented from manipulating a URL or a value in
the worksheet that would give them access to restricted values.
You must create a component for every Table Validated field requiring an LOV within the document. A Java
class has been provided to offer this functionality, but metadata must be entered for each LOV to handle
properties such as table headers and window captions. Use the following steps to create a Table Validated
Component.
5.1.2.1. Access the Parameter List UI and enter a name and Code for your parameter list. Make
the name meaningful and relate it to the field. The Code needs to be the Code you entered for the
component in BNE_COMPONENTS_B.PARAM_LIST_CODE. Check the Persistent Box and add
comments if needed. Press Save when finished.
5.1.2.2. Add the Following Parameters to the Parameter list by pressing Add Another Row.
33
Company Confidential - For internal use only
Parameter Name table-column-alias
Value If the table-select-column does not exist in table-
columns, then enter the table-select-column here to
create an alias for the table-column you wish to have
inserted into the sheet. This is a comma delimited
list.
Description
Parameter Definition Copy the 231:TABLE_COLUMN_ALIAS parameter
definition under your own application ID and use
the copy for this parameter.
The following parameters are not required for the LOV parameter list. Only add them if you wish to override default
behavior:
34
Company Confidential - For internal use only
definition under your own application ID and use
the copy for this parameter.
Default used when this 450
parameter is not added
to the list
The parameter definitions you created for the parameters above can be re-used when creating more than one table
validated component within your application.
The following two parameters will require a new definition to be created every time a parameter list is created for a
table validated component. This is because their values are translated and specific to each LOV.
Definition:
Name Table-headers {Name of Interface Column}
Source (Integrator Name):Components
Category Data
Description Comma-delimited list of table column headers. This
parameter has an individual parameter definition so
it can get translated default values.
Data Type String
Default Value (Enter the headers of each column you wish to
appear in the LOV)
Store as Translatable Checked
Max Size 100
Display Size 100
Name window-caption
Value (Leave blank to use default in parameter definition
this is the title to be placed on window caption bar)
Description Enter meaningful description
Parameter Definition Press the Definition Button to create definition
Definition:
Name Window-caption {Name of Inter face column}
35
Company Confidential - For internal use only
Source (Integrator Name):Components
Category Data
Description This is what is displayed in the window caption
Data Type String
Default Value Enter what you want to be displayed in the LOV
windows caption.
Store as Translatable Checked
Max Size 100
Display Size 100
36
Company Confidential - For internal use only
5.2. Creating Date Picker Components
Web ADI has developed a standard Calendar Component to act as a LOV for date fields. A Java class has
been provided to offer this functionality, but metadata must be entered for each LOV to handle properties
such as the window caption. Use the following steps to create a Calendar Component.
5.2.2.1. Access the Parameter List UI and enter a name and Code for your parameter list. Make
the name meaningful and relate it to the field. The Code needs to be the Code you entered for the
component in BNE_COMPONENTS_B.PARAM_LIST_CODE. Check the Persistent Box and add
comments if needed. Press Save when finished.
5.2.2.2. Add the Following Parameters to the Parameter list by pressing Add Another Row.
37
Company Confidential - For internal use only
Parameter Name table-select-column
Value Enter the
BNE_INTERFACE_COLS_B.INTERFACE_COL_NAM
E of the column you wish the selected LOV to update
in the document
Description
Parameter Definition Copy the 231:TABLE_SELECT_COLUMN parameter
definition under your own application ID and use the
copy for this parameter
The following parameters are not required for the LOV parameter list. Only add them if you wish to override default
behavior:
The parameter definitions you created for the parameters above can be re-used when creating more than one
component within your application.
The following two parameter will require a new definition to be created every time a parameter list is created for a
table validated component. This is because their values are translated and specific to each LOV.
Name window-caption
38
Company Confidential - For internal use only
Value (Leave blank to use default in parameter definition
this is the title to be placed on window caption bar)
Description Enter meaningful description
Parameter Definition Press the Definition Button to create definition
Definition:
Name Window-caption {Name of Inter face column}
Source (Integrator Name):Components
Category Data
Description This is what is displayed in the window caption
Data Type String
Default Value Enter what you want to be displayed in the LOV
windows caption.
Store as Translatable Checked
Max Size 100
Display Size 100
This may be done by extending the BneCalendarComponent and over-riding some (or
all) of the following methods:
listOfValuesInit()
getListOfValueParameters()
getMinCalendarValue()
39
Company Confidential - For internal use only
getMaxCalendarValue()
getDefaultCalendarValue()
Your field may require an LOV or validation that is more complex than Table Validation. Valid fields could depend
on a number of parameters, including some entered or existing in the document. Complex business rules will require
the creation of a Java Validated record in BNE_INTERFACE_COLS_B. Creating a Java validated field involves the
following steps:
9 Assign Component to a column in BNE_INTERFACE_COLS_B. This includes putting the component key in
VAL_COMPONENT_CODE, an application ID in BNE_VAL_COMPONENT_APP_ID and entering the Java
Class in VAL_OBJ_NAME.
Java validation includes the following two types of functionality; provide List of Values
for fields in the Web ADI documents and validation of data at upload time. For the
purposes of this document, each shall be referred to as LOVs (List of Values) and Upload
Validators respectively.
Java Validation allows business rules to be used for the following purposes:
There are three main Java classes associated with Java Validation:
For more complex solutions where the validation of one interface column is conditional
upon the validation of one or more other interface columns, a Group Validator will need
to be implemented.
40
Company Confidential - For internal use only
For example: if any one of three columns is required to contain a value at the time of
upload, but none of the columns is defined as a required column, then a Group Validator
can be used at Upload time to ensure that one of the three columns contains a value.
As part of the Java Validation implementation, metadata corresponding to the LOV and
Upload Validator must be seeded in the BNE database schema.
Sample metadata and sample Java Classes are included in the Appendices of this
document.
This documentation assumes that you already have fundamental Web ADI objects
created, i.e. an Integrator, Interface, Interface Columns, Layout and Mapping.
NOTE: Only experienced Java developers should write the three Java classes required to
implement an LOV or Upload Validator.
Prefix each class name with your application short name, e.g. Bne, Gl, etc.
Use the same name for all three classes that make up the LOV and/or Upload Validator.
This usually includes the name of the field in the Web ADI document for which the Java
Validation is being implemented.
BnePeriodNameSQL, BnePeriodNameValidator,
BnePeriodNameComponent
Use the Java standard of InitCaps for your class names, as shown in the example above.
This class contains all the SQL queries required to generate the List of Values (LOV)
applicable to the Interface Column, and all the SQL queries required to perform the
Upload Validation for the same Interface Column. Usually these queries are the same.
The SQL queries required for the Upload Validator include all queries required to verify
business rules pertaining to the data being uploaded into the database. Usually one or
more queries are required to validate a single field.
For example (as per the BneOAPeriodNameSQL class Appendix A), when validating
the Period Name column in a GL Journal, you may need the following SQL queries:
41
Company Confidential - For internal use only
1. When uploading an Accounting Date and a Period Name, you need to run a
query to confirm that the Accounting Date falls within the Period.
Both queries are required to ensure that a more accurate and meaningful error message
is displayed to the user.
For a Java Validator that incorporates several business rules, several queries may be used
to generate different Lists of Values dependent on the business rules. The following two
examples help to illustrate how this can be done:
IF A and B THEN
ELSE IF A
ELSE
END IF
ELSE
END IF
For a Validator/LOV requiring only one SQL query, the following signature should be used for
the Constructor:
For a Validator/LOV requiring two or more SQL queries, the following signature should be
used for this Constructor:
42
Company Confidential - For internal use only
int queryNumber,
String extraSQL)
The parameters for the SQL Java class Constructor are as follows:
1.1.1.6 context
This parameter contains all the JDBC session information required to prepare the SQL query.
1.1.1.7 queryNumber
This parameter is used to identify the query to be prepared when the Constructor is called.
A switch statement is used to hold the different queries using a number to represent each
case. It is important to include a default case in the switch statement to handle any invalid
query numbers.
For example:
switch (queryNumber)
{
case 1:
query.append(SELECT );
break;
case 2:
query.append(SELECT );
break;
default:
throw IllegalArgumentException (with meaningful message);
}
extraSQL
This parameter is used to pass the value selected from the LOV by the user in the Web ADI
document. This is only used by the Upload validator, and is appended to the appropriate
query to restrict the results using the user-selected value.
43
Company Confidential - For internal use only
The SQL queries in this class will be run:
Firstly to generate the List of Values to be displayed in the List of Values page; and
For Upload Validation extra SQL is appended to the Where criteria of the query limiting the
query results to values matching the user-selected value. Therefore, the value being
uploaded is only valid if one or more rows are returned by the query, and invalid when no
rows are returned.
The Web ADI platform has been designed to allow the use of Java Validators to allow more
complex logic to be used to validate the data in a spreadsheet before it is uploaded into the
database.
Some examples of the complex logic that can be incorporated into the Java Validators:
Profile options determine the validation that will be done depending on the profile
option value.
Other system setup anything that can be queried from the database can be used
within your validator class to assist in validating the interface column(s) in the Web
ADI document.
There are two types of Java validators: Field Validators and Group Validators.
Field Validators
Individual interface columns can be validated using a field validator. This is the most
common type of validator. Other interface column values for the same record that have been
entered in the spreadsheet can be used to help validate the individual interface column.
Group Validators
An interface column can be part of a group. All columns that form part of the group are
validated as a complete set of columns.
For example, the SEGMENT columns in the GL_INTERFACE table that make up an
Accounting Flexfield account need to be validated as a complete set, not as individual values.
So, by identifying each SEGMENT column as being part of an
ACCOUNTING_FLEXFIELD_GROUP, when group validation is performed, all of the
segment values for the group are collected and validated together as a set.
The metadata and code together determine whether a validator is a field or group validator.
Refer to the section: Metadata for Java Validation.
44
Company Confidential - For internal use only
1.1.1.8 Implementing a Field Validator Java Class
An individual field validator class should be a public class that extends the
BneUploadValidator class. The BneUploadDomainInterface and BneUploadValidatorInterface
are both implemented in the BneUploadValidator abstract class.
All validators should extend the BneUploadValidator class, which provides default
implementations of a number of methods in the two Interfaces. The default implementations
do not enforce any additional validation.
startupValidator
This method is called once at the beginning of the Upload Validation process. Use this
method to perform setup steps that only need to be performed once. For example, look
up a profile option value. This value is not different for each row of data, and therefore
only needs to be derived once.
validateColumn
This method is called once for each different value being uploaded for the interface
column. If the value being validated is the same as the last value that was validated (in
the same upload), the validation will not occur again. The signature for this method is as
follows:
45
Company Confidential - For internal use only
The logic for this method is as follows:
- Create a SQL handle to the SQL Query by calling the SQL class constructor
(pass the additional WHERE clause criteria in the extraSQL parameter)
E.g. COLUMN_NAME = ?
- Run the SQL (from the SQL class) passing the following values:
- CurrentColumn value (bind variable for extraSQL)
- Any other required values from the columnValues hashtable
- Any other required values (derived within the class)
shutdownValidator
This method is called once at the end of the Validation process. Ensure that any SQL
handles are closed in this method. The signature for this method is as follows:
finalValidation
This method is processed after all rows have been validated. This allows for validation to
be carried out that for the entire set of rows in the Upload document, if required. The
signature for this method is as follows:
uploadError
This method can be used to simplify the formatting of an Upload Error message. This is
an error message and will prevent the upload from occurring. A message should be
passed to this method in the msgStr parameter. This message should explain what the
error is and how the error can be fixed. The signature for this method is as follows:
46
Company Confidential - For internal use only
uploadException
This method can be used to simplify the formatting of an Upload Exception message.
This is an error message and will prevent the upload from occurring. Two messages
should be passed to this method. The first message should describe the error that has
occurred or what caused the error. This message should be passed to the method in the t
parameter. The second message should explain how the error can be fixed. This message
should be passed to this method in the msgStr parameter. The signature for this method
is as follows:
uploadWarning
This method can be used to simplify the formatting of a Warning message. This is a
warning message only and will not prevent the upload occurring. The signature for this
method is as follows:
getDomainParameters
This method must create and return a String array of all the interface column names
whose values are required to generate the List of Values.
getDomainValues
This method must generate and return an SQL result set containing the values to be
displayed in the List of Values.
Create a SQL handle to the SQL Query by calling the SQL class constructor
(the extraSQL parameter is usually passed as null)
47
Company Confidential - For internal use only
Run the SQL (from the SQL class) passing any values required for binding
e.g. Any other required values from the columnValues hashtable,
Any other required values (derived within the class)
shutdownValidator
This method is called once at the end of the LOV/Validation process. Ensure that any
SQL handles are closed in this method. The signature for this method is as follows:
Group validation is performed after all individual field validation is complete. Classes that are
written as group validators must extend the BneUploadGroupValidator abstract class. The
methods included in this class are as follows:
startupValidator
This method is called once at the beginning of the LOV/Validation process. Use this method
to perform setup steps that only need to be performed once. For example, look up a profile
option value. This value is not different for each row of data, and therefore only needs to be
derived once.
validateGroup
This method validates a group of values in a single row. It is called repeatedly throughout
the upload validation process. Access to the entire row of data is available via the
columnValues Hashtable.
48
Company Confidential - For internal use only
BneInterfaceCol interfaceCol)
shutdownValidator
This method is called once at the end of the LOV/Validation process. Ensure that any SQL
handles are closed in this method. The signature for this method is as follows:
finalValidation
This method is processed after all rows have been validated. This allows for validation to
be carried out that for the entire set of rows in the Upload document, if required. The
signature for this method is as follows:
uploadError
This method can be used to simplify the formatting of an Upload Error message. This is
an error message and will prevent the upload from occurring. A message should be
passed to this method in the msgStr parameter. This message should explain what the
error is and how the error can be fixed. The signature for this method is as follows:
uploadException
This method can be used to simplify the formatting of an Upload Exception message.
This is an error message and will prevent the upload from occurring. Two messages
should be passed to this method. The first message should describe the error that has
occurred or what caused the error. This message should be passed to the method in the t
parameter. The second message should explain how the error can be fixed. This message
49
Company Confidential - For internal use only
should be passed to this method in the msgStr parameter. The signature for this method
is as follows:
This class contains all the business logic and setup information for generating the List of Values
(LOV) page for an Interface Column in the Web ADI document. This class is not required for
the implementation of an Upload Validator.
Properties relating to the information displayed in the LOV window and how it will be
displayed can be derived from four different places. These properties are referred to as
Component Parameters. Web ADI uses the following order of precedence when using these
Component Parameters to generate the LOV page:
2. Parameter List items values can be defined against each item in a Parameter List.
4. Hard-coded defaults - when values are not defined in metadata or set within the
Component Java class, Web ADI will use the hard-coded defaults to create the LOV
page.
50
Company Confidential - For internal use only
Component Parameter Default Valid Values Description
Name
detail.
table-block-size 10 Must be a number. Determines the number of records to
display.
table-long-list false true, false Determines if the results are too long to
display and restricts first; values are; { true,
false }
table-select-column Must be text. Select column, comma-seperated list of
columns to be selected. If aliases exist then
use the alias name. Example: NAME,DEPT
table-select-type _SINGLE_SELECTION _SINGLE_SELECTION, Type of table selection; values are; {
_MULTIPLE_SELECTION SINGLE , MULTIPLE }"
table-filter true true, false Display table filter on select columns;
values are; {true, false}
window-caption Search and Select Must be text. Title to place on window caption bar.
window-width 350 Must be a number. Width of display window.
window-height 450 Must be a number. Height of display window
Business logic is usually incorporated in the Validator class, however, the same logic can be
used in the Component class to determine the type of LOV that is displayed. For example, for a
date field, a Calendar may be displayed in one case, but a list of specific dates in another case.
Lists Of Values are CABO/UIX pages with exposed DOM interaction for use with Viewers.
The Component class determines the look and feel of the CABO/UIX page and the data that
will be displayed on the page.
The Component class must extend the BneAbstractListOfValues abstract class. The methods
included in this class are as follows:
init method
This method instantiates the Validator class and then calls the getDomainParameters
method using the instantiation to create a String array of the interface column names
required by the validator. The signature for this method is as follows:
Parameter Description
51
Company Confidential - For internal use only
getListOfValueParameters method
This is an abstract method within the BneAbstractListOfValues class and therefore requires
an implementation within the Component class. This method creates a BneParameterList
object consisting of one record for each parameter in the parameter list created by the
getDomainParameters method call. Each record consists of the Parameter name and a
description for the parameter in the format Oracle Applications
GL_INTERFACE.<parameter_name> field.. The signature for this method is as follows:
handleListOfValues method
This is an abstract method within the BneAbstractListOfValues class and therefore requires
an implementation within the Component class. This class calls public methods to set up the
information for the table that will be displayed in the LOV, for example: setTableFilter,
setPageTitle, setTableData, setTableColumns, setTableHeaders, and setTableSelectColumn.
Return null from this method. The signature for this method is as follows:
Parameter Description
Call handlePageParameters
52
Company Confidential - For internal use only
handlePageParameters method
This method retrieves the filter field and filter value from the LOV page using an Http
Request. Two String instance variables need to be defined to hold these two values:
m_filterField and m_filterValue.The signature for this method is as follows:
Parameter Description
53
Company Confidential - For internal use only
getTableData method
This method generates the result set for the LOV by calling the Validator class
getDomainValues method. This method processes each record in the result set returned by
the getDomainValues method to create a Vector containing all the valid values for the LOV.
A DictionaryData construct is created using the data in the Vector. This Validator class
shutdownValidator method is called to close off any open SQL handles. The signature for
this method is as follows:
Parameter Description
getLOVProcessorType method
This is an abstract method within the BneAbstractListOfValues class and therefore requires
an implementation within the Component class. This method must return an LOV type. The
LOV types have been defined using the following constants (include java class
oracle.apps.bne.framework.BneConstants to use these contants):
The LOV Processor Type is set at the time the Document is created. The signature for this
method is as follows:
54
Company Confidential - For internal use only
getComponentName method
This method returns a hard-coded string containing the name of the component, i.e.
BneOAFieldName.
getComponentVersion method
This method returns a hard-coded string containing the revision number of the component.
Use the token $ Revision: $ as your string. This will return the current revision number for
the Component class.
BNE_PARAM_DEFNS_B, BNE_PARAM_DEFNS_TL
BNE_PARAM_LISTS_B, BNE_PARAM_LISTS_TL
BNE_PARAM_LIST_ITEMS
BNE_COMPONENTS_B, BNE_COMPONENTS_TL
BNE_INTERFACE_COLS_B
Integrator Developers should use the Parameter UI supplied with Web ADI to create the
Parameter List, Parameter List Items and Parameter Definitions. The Parameter UI can be
accessed using the following URL:
http://server:port/oa_servlets/oracle.apps.bne.webui.BneApplicationService?bne:page=BneParameter
This section describes each of the columns in the tables listed above. Sample metadata is
included in Appendix D - Sample Metadata for the Period Name Java Validation.
BNE_PARAM_DEFNS_B
55
Company Confidential - For internal use only
Column Name Data Type Size Description
Definition.
PARAM_SOURCE VARCHAR2 240 This is the source requiring the parameter definition. This
is a text entry field.
PARAM_CATEGORY NUMBER 5 Categorys include: Miscellaneous, Position, Appearance,
Behaviour, Data, Field.
DATATYPE NUMBER 1 Data Types include: String, Number, Date, Boolean.
DEFAULT_REQUIRED_FLAG VARCHAR2 1 Is a value required for this parameter? Y/N
DEFAULT_VISIBLE_FLAG VARCHAR2 1 Is this parameter visible to the user? Y/N
DEFAULT_USER_MODIFYABLE_FLAG VARCHAR2 1 Is the user able to change this parameter value? Y/N
DEFAULT_STRING VARCHAR2 2000 Set a default value of type VARCHAR2.
DEFAULT_DATE DATE Set a default value of type DATE.
DEFAULT_NUMBER NUMBER Set a default value of type NUMBER.
DEFAULT_BOOLEAN_FLAG VARCHAR2 1 Set a default value of type boolean.
DEFAULT_FORMULA VARCHAR2 240 Supply a format mask for the default value.
VAL_TYPE VARCHAR2 2 Validation types include: None, Fnd Lookups, Value Set
MAX_SIZE NUMBER 5 The maximum size of the parameter value.
DISPLAY_TYPE NUMBER 1 Display Types include: List Box, CheckBox, Radio
Buttons, Text Field, Password Field.
DISPLAY_STYLE NUMBER 1 Display Styles include: None, Vertical Horizontal
DISPLAY_SIZE NUMBER 5 The size of the value to be displayed to the user. This
should not exceed the MAX_SIZE value.
BNE_PARAM_DEFNS_TL
BNE_PARAM_LISTS_B
56
Company Confidential - For internal use only
BNE_PARAM_LISTS_TL
Parameters that are different from the hard-coded defaults are included in the Parameter List.
Add one item for each parameter.
1.1.1.10 BNE_PARAM_LIST_ITEMS
Link an existing Parameter Definition to a Parameter List item by setting the
PARAM_DEFN_APP_ID and PARAM_DEFN_CODE values.
BNE_COMPONENTS_B
Link an existing Parameter List to a Component by setting the PARAM_LIST_APP_ID and
PARAM_LIST_CODE values.
57
Company Confidential - For internal use only
Column Name Data Type Size Description
APPLICATION_ID NUMBER 15 This is the APPLICATION_ID for your Application, e.g. The
APPLICATION_ID for GL is 101.
COMPONENT_CODE VARCHAR2 30 Unique Component code. This should be as meaningful as
possible for the Component, e.g.
GL_ACCOUNTING_DATE_COMPONENT. Must be all
caps.
OBJECT_VERSION_NUMBER NUMBER 15 This is a version number for the Component. Set to 1 on
creation. Increment this number every time a value changes
for any of the columns in this record.
COMPONENT_JAVA_CLASS VARCHAR2 240 This must be the fully qualified Component java class name,
e.g.
oracle.apps.bne.integrator.components.BneFieldNameComp
onent
PARAM_LIST_APP_ID (FK1) NUMBER 15 The Parameter List Application ID.
PARAM_LIST_CODE (FK1) VARCHAR2 30 The Parameter List Code.
BNE_COMPONENTS_TL
APPLICATION_ID NUMBER 15 This is the APPLICATION_ID for your Application, e.g. The
APPLICATION_ID for GL is 101.
COMPONENT_CODE VARCHAR2 30 Unique Component code. This should be as meaningful as
possible for the Component, e.g.
GL_ACCOUNTING_DATE_COMPONENT. Must be all
caps.
LANGUAGE VARCHAR2 4 Standard Apps Language column.
SOURCE_LANG VARCHAR2 4 Standard Apps Language column.
USER_NAME VARCHAR2 240 A meaningful name for the Component.
BNE_INTERFACE_COLS_B
APPLICATION_ID NUMBER 15 This is the APPLICATION_ID for your Application, e.g. The
58
Company Confidential - For internal use only
Column Name Data Type Size Description
APPLICATION_ID NUMBER 15 This is the APPLICATION_ID for your Application, e.g. The
APPLICATION_ID for GL is 101.
INTERFACE_CODE VARCHAR2 30 Unique Interface code. This should be as meaningful as
possible for the Interface, e.g. GL_INTERFACE_115. Must
be all caps.
SEQUENCE_NUM NUMBER 15 Each interface column for a single Interface must have a
unique number. Numbering must start at 1 and increment
by one for each interface column.
INTERFACE_COL_TYPE NUMBER 15 As the parent of a Group, the interface column type must be
set to 2.
INTERFACE_COL_NAME VARCHAR2 50 This is the name of the Group with _PARENT appended to
it.
ENABLED_FLAG VARCHAR2 1 Is the group/parent column enabled? Y/N
REQUIRED_FLAG VARCHAR2 1 The Group Validator will always run when pre-validation is
checked in the Upload Parameters page.
DISPLAY_FLAG VARCHAR2 1 This column is not used. This is set to the default of N.
READ_ONLY_FLAG VARCHAR2 1 This column is not used. This is set to the default of N.
NOT_NULL_FLAG VARCHAR2 1 This column is not used. This is set to the default of N.
SUMMARY_FLAG VARCHAR2 1 This column is not used. This is set to the default of N.
MAPPING_ENABLED_FLAG VARCHAR2 1 This column is not used. This is set to the default of N.
GROUP_NAME VARCHAR2 30 This is the name of the group. The group/parent interface
column and all interface columns to be included in the
group must have the same GROUP_NAME.
59
Company Confidential - For internal use only
Column Name Data Type Size Description
APPLICATION_ID NUMBER 15 This is the APPLICATION_ID for your Application, e.g. The
APPLICATION_ID for GL is 101.
INTERFACE_CODE VARCHAR2 30 Unique Interface code. This should be as meaningful as possible for the
Interface, e.g. GL_INTERFACE_115. Must be all caps.
SEQUENCE_NUM NUMBER 15 Each interface column for a single Interface must have a unique number.
Numbering must start at 1 and increment by one for each interface
column.
GROUP_NAME VARCHAR2 30 The GROUP_NAME defined against the Group/Parent interface column
must be inserted in this column for all Interface Columns to be included
in the Group Validation.
60
Company Confidential - For internal use only
6. Defining an Importer
If an Integrator is uploading to interface tables, it is possible to have Web ADI automatically invoke the program
used to move data from the interface tables to application base tables. The upload process will call the import
program after records have been inserted into the interface tables. The results of the import program can be
retrieved to users. All the information Web ADI needs to call the import program is defined in metadata. The
following steps to define an Importer:
9 Define a parameter list for each parameter (step) in the master list
You must choose what import type your integrator will use, then update Web ADI metadata.
Value Description
1 Asynchronous concurrent request
2 Synchronous concurrent request
3 PL/SQL API
The import process is broken down into individual steps/processes that need to occur to perform an import.
These steps are metadata driven and can be arranged differently to cater to each type of import. The steps are
defined within a master parameter list assigned to the Integrator. With exception to the
SUCCESS_MESSAGE, each step/parameter in the master list has its own parameter list to provide the
required metadata to complete its part of the import process.
6.2.1.1. Access the Parameter list UI and enter a name for your import parameter list. It
should be in the form of: (Integrator Name): Import Master List. A parameter list
ID will be given as soon as you press Save.
6.2.1.2. Associate the parameter list with your integrator by inserting the PARAM_LIST_ID
created above into BNE__INTEGRATORS.IMPORT_PARAM_LIST
62
Company Confidential - For internal use only
There may be multiple success messages.
There may be a row mapping but one is not required for an import. If a success
message is not defined then a standard Web ADI success message will be returned.
There must not be any ERROR_LOOKUP, ERRORED_ROWS steps.
There may be only one CLEANUP_SQL or CLEANUP_PLSQL step, but not both.
The associated parameter lists with each of these parameters will define what the
metadata is for the individual steps.
The PL/SQL API call is used when a concurrent request is not to be used as the method of
import. An API call does not include a CONCURRENT_REQUEST step.
63
Company Confidential - For internal use only
6.2.2.2. View the descriptions of each step in 6.3 and add the steps to the master parameter
list using the Add Another Row button in the Parameter UI. Use the Step Names
described in 6.2.2 for the Parameter Name.
Parameter lists and Attributes will need to be defined for each step in the master list. See the selections
below for instructions on setting up the metadata for each type of import step.
The SQL statement step type defines the metadata required to perform a SQL clause. If the SQL is a select
statement then the values that have been selected can be retrieved back into the collection that is stored
for retrieving values from queries that have been executed. Bind variables can be used to define the
inputs of the query and Return variables are used to retrieve values from the SQL. Bind variables are
used to define Insert and Update statements without knowing the data at design time. The return
variables are used in select statements, and represent the columns in the select declaration. Return values
are values from columns defined in the select declaration section of the select query (e.g. status from
select status from gl_interface). To enable a SQL statement step:
6.3.1.1. Create a new parameter list through the parameter UI. Name the parameter list:
(Integrator Name): SQL Step.
6.3.1.2. Enter the parameters for the SQL step parameter list. The first parameter in the list is
the SQL statement that is to be executed and the rest of the parameters identify
bind/return variables.
Below is an example of a SQL step parameter list. The SQL statement is defined in
the first parameter and the bind variables used in the SQL statement are defined
thereafter:
6.3.1.2.1. Press Add Another Row to define the SQL statement to run. Once the Define
Parameter window opens, set the Data Type to String, and enter the SQL statement into
the Value field. Use the following format for a SQL statement: SELECT column_names
64
Company Confidential - For internal use only
FROM table_names WHERE column = $PARAM$.parameter_name. DO NOT enter a
semi-colon at the end of the SQL statement.
6.3.1.2.2. Press Add Another Row to define the parameters being used in the SQL
statement. The name of the parameter is used to map between the SQL statement and
the bind/return variables. In the above definition, the $PARAM$.parameter_name is
replaced with the value that is derived from the metadata for the parameter in the
parameter list with the same name (i.e parameter_name). This method of replacing
$PARAM$ tokens with the associated parameter values works for any SQL statement.
The parameter in the SQL statement must be the same case as the parameter name in the
list.
For select statements, the column_names also needs to be defined as parameters in the
list. Make sure to the name of the parameter matches the colum_name in the SQL
statement. The parameter in the SQL statement must be the same case as the parameter
name in the list.
6.3.1.2.3. Press the edit button next to the Attributes button in the Parameter Definition
screen. The attributes screen will let you enter metadata that determines how the
parameter value is derived.
ATTRIBUTE1 Whether the parameter is defining a bind or a return variable. Web ADI stores RETURN
resulting values for columns in select statements if ATTRIBUTE1=RETURN. BIND
ATTRIBUTE2 The unique name of the bind/return variable to be used in subsequent steps. The
value added to the IMPORT hashtable uses the value in this column as the key.
ATTRIBUTE3 The Source the parameter value will be retrieved from. IMPORT
ENV
REQUEST
ATTRIBUTE4 What value is to be used to get the value from the Source
ATTRIBUTE5 Data type of the bind/return value
ATTRIBUTE6 Position of the return value in the select statement [optional]. Web ADI looks up 1..Number
the value for the parameter in the SQL statement result set by using the column of return
position in the select statement. If no value is supplied for ATTRIBUTE6 or is values
invalid, then the value will be looked up using the parameter name. Web ADI will
have better performance if a valid value is entered in this column.; it will take
more time to look up the value if the parameter name is used.
Value Description
IMPORT Value will come from a previously executed step (SQL query, PL/SQL call, Sequence
number retrieval or from the group definition). The hashtable key for the value is entered
in the name column (ATTRI BUTE4). Use this Source if you want to derive the value
from the value of a column that has been uploaded by the user. To do this, the interface
column needs to be identified in a Group step. Enter the
interface_table_name.column_name in ATTRIBUTE4.
ENV An environment variable. Valid names (ATTRIBUTE4) are userid, language, respid,
appid.
REQUEST Use this source type when parameter values are sent from the upload parameters page.
Names (ATTRIBUTE4) need to match the param_name in the parameter list for the
UPLOAD_PARAM_LIST.
Note: A limitatio
6.3.1.3. En of this
nter design is that
the parameter list currently
ID createda above
SQL statem
in theent
SQLis restricted to
step parameter in the master list.
2000 characters.Open the Define Parameter screen for the SQL parameter; set the Data Type to
Number, and enter the parameter list ID in the Value field.
65
Company Confidential - For internal use only
6.3.1.4. Example: To execute the SQL call: select je_source_name from gl_je_sources where
user_je_source_name = $PARAM$.je_source_param. The je_source_name returned
will be stored in the hash table and available for use in a later step. A bind variable
will be used to edit the where clause. This value will come from a value the user
uploades from the document on the desktop to GL_INTERFACE.
USER_JE_SOURCE_NAME.
6.3.1.4.1. Create the Following Parameters in the SQL step parameter list.
Sequence number 1
Name SQL_Statement
Value select je_source_name from gl_je_sources where user_je_source_name =
$PARAM$.je_source_name_param
Data Type String
Sequence number 2
Name Je_source_name
SEQ_NUM 3
PARAM_NAME Je_source_param
6.3.1.4.2. Define Atributes for each parameter by pressing the edit button next to the
Attibutes label in the Define Parameter screen.
6.3.1.5. Enter the parameter list ID created for the SQL step parameter in the master list.
Open the Define Parameter screen for the SQL parameter; set the Data Type to Number, and
enter the parameter list ID in the Value field.
6.3.2.1. Create a parameter list for the PLSQL step. Name it (Integrator Name):PLSQL Step
66
Company Confidential - For internal use only
6.3.2.2. Press the Add Another Row in Define Parameter List screen for the PLSQL step.
Name the Parameter: (Procedure Name). Press the edit attributes button to enter
information about the PL/SQL procedure.
6.3.2.3. Create additional parameters in the list for every parameter in the API call. A record
must be created for all the API parameters. Attributes must be defined for every
parameter as well. Press the edit attributes button in the Define Parameter screen for
each parameter in the list to access the attribute window.
Column DESCRIPTION
PARAM_NAME True
STRING_VALUE Y
PARAM_NAME False
STRING_VALUE N
67
Company Confidential - For internal use only
ATTRIBUTE10 is used when the data provided needs to have some formatting
applied before it gets passed in as a parameter. This attribute should only be used
in very rare cases. The main case where this attribute would be used is for passing
a DATE value from the import into a PL/SQL API as a VARCHAR2 parameter. In
the situation where a the date is required in MM/ DD/YYYY format, the
ATTRIBUTE10 value would be: TO_CHAR(?, MM/DD/YYYY)
Value Description
IMPORT Value will come from a previously executed step (SQL query, PL/SQL call, Sequence
number retrieval or from a column value in a group definition). The hashtable key for the
value is entered in the name column (ATTRI BUTE8). Use Import if you would like to use
a value the user has entered into the desktop document; make sure that column is
included in a GROUP step. Enter tablename.column from the group definition in
ATTRIBUTE8.
ENV An environment variable. Valid names (ATTRIBUTE8) are userid, language, respid,
appid.
REQUEST Use this source type when parameter values are sent from the upload parameters page.
Names (ATTRIBUTE8) need to match a parameter name for the parameter list used for
UPLOAD_PARAM_LIST.
6.3.2.4. Enter the parameter list ID created above in the PLSQL step parameter in the master
list. Open the Define Parameter screen for the PLSQL parameter; set the Data Type
to Number, and enter the parameter list ID in the Value field.
6.3.3.1. Create a parameter list through the parameter list UI. Give the Parameter list a name
in the form of: (Integrator name): Concurrent Request Step.
6.3.3.2. Use the Add Another Row button to add the following parameters to the parameters
list.
Seq 1
Name Application
Data Type String
Value (Leave Blank)
Seq 2
Name Program
Data Type String
Value (Leave Blank)
Seq 3
Name Description
Data Type String
Value (Leave Blank)
68
Company Confidential - For internal use only
Seq 4
Name Run Date
Data Type String
Value (Leave Blank)
Seq 5
Name Sub request
Data Type String
Value (Leave Blank)
Seq N+1
Name End Of Concurrent Request Parameters
Data Type String
Value (Leave Blank)
Seq N+2
Name Rest of Parameters Defaults
Data Type String
Value (Leave Blank)
6.3.3.2.1. Add the following Attributes to all the parameters in the list except the Last
Parameter.
6.3.3.2.2. Add the following Attributes to the Rest of Parameter Defaults parameter
ATTRIBUTE DESCRIPTION
6.3.3.2.3. Enter the parameter list ID created above in the CONCURRENT_REQUEST step
parameter in the master list. Open the Define Parameter screen for the CONCURRENT-
69
Company Confidential - For internal use only
REQUEST parameter; set the Data Type to Number, and enter the parameter list ID in
the Value field.
6.3.4.1. Create a parameter list using the parameter UI. Name the list (Integrator Name):
Sequence
6.3.4.2. Press the Add Another Row button to add a parameter to the list. The Data Type
should be String. The name you enter for the parameter is the key you will use to
reference the sequence value from the hash table. Enter the name of the sequence in
the Value field.
6.3.4.3. Example:
Field DESCRIPTION
Name l_run_id
Data Type String
Value GL_JOURNAL_IMPORT_S
6.3.4.4. Enter the parameter list ID created above in the SEQUENCE step parameter in the
master list. Open the Define Parameter screen for the SEQUENCE step parameter; set the
Data Type to number, and enter the parameter list ID in the Value field.
A common usage for the group step is to save values uploaded by the user to the hash table, which can
then be referenced by later steps. For example, perhaps your users are entering Person ID into a
spreadsheet, which must then be used as a parameter in the call to a PL/SQL import program (PLSQL
step). To accomplish this, the TABLENAME.PERSON.ID would be added to the group definition.
During upload, Web ADI will look to see what value was uploaded to TABLENAME.PERSON.ID and
store it in the hash table. This value can then be used when calling an import program (PLSQL step).
6.3.5.1. Create a parameter list in the Parameter UI. Make the Name of this list (Integrator
Name): Group Step.
6.3.5.2. Use the Add Another Row button to create a parameter in the list for every column
you wish to be part of the group.
Field DESCRIPTION
All the steps in the master list are executed for every group of records uniquely
identified by the group definition. As a consequence, you are unable to repeatedly
perform all of the steps except for one and then run that step separately. For
70
Company Confidential - For internal use only
example, you could not run the SQL to insert into the GL_INTERFACE_CTL table
multiple times but only submit a concurrent request once.
6.3.5.3. Enter the parameter list ID created above in the group step parameter in the master
list. Open the Define Parameter screen for the GROUP parameter; set the Data Type
to Number, and enter the parameter list ID in the Value field.
6.3.6.1. Look up the master parameter list and press the Update button next to the
SUCCESS_MESSAGE parameter.
6.3.6.2. Press the Definition button in the Define Parameter screen; set the Data Type to
String, and enter the success message in the Default value field. An example would
be: Journal Import Request ID $import$.requested.
71
Company Confidential - For internal use only
6.3.7. Row Mapping
The Row Mapping step enables Web ADI to match a row in the interface table with its corresponding row
in the spreadsheet. Columns in the interface table are identified in this step to create the primary key in
identifying unique records in both the spreadsheet and interface table. Web ADI will map the interface
table rows to spreadsheet rows using this key. In most cases this set of columns will be the primary key
of the interface table. The primary use of this mapping is to be able to return error messages for
individual rows that failed. The name field for each parameter stores the column names that are to be
used in the mapping.
6.3.7.2. Use the Add Another Row button to add a parameter for every column required to
be in the mapping (uniquely identifies records).
Field DESCRIPTION
6.3.7.3. Enter the parameter list ID created above in the Value field for the
ROW_MAPPING step record in the master list. Make sure the Data Type is set to Number.
If there are no columns in the interface that can provide a one-to-one mapping between the interface row
and the row in the spreadsheet, then the best that the error reporting can be is a message in the upload
page stating that there was an error with the import.
The Errored Row Definitions step enables Web ADI to identify rows that have failed the import. A SQL
query is defined that will be run by Web ADI to determine the rows that did not pass validation done by
the import program.
The SQL Query can contain Bind variables which can be used to provide input values into the query.
The query provided must contain at least one column in the select clause but the SELECT statement can
be SELECT * and the error rows step will know what columns are in the interface table. It is
reccomended that SELECT * be used to make sure all of the necessary values are retireved in the SQL
statement.
72
Company Confidential - For internal use only
IMPORT Value will come from a previously executed SQL query, PL/SQL
call, Sequence number retrieval or from the group definition.
ENV An environment variable
REQUEST Value will come from the HTTP request (Upload Parameters).
6.3.8.4. Enter the parameter list ID created above into the value field in the
ERRORED_ROWS parameter in the master parameters list. Make sure the Data Type for the
ERRORED_ROWS parameter is Number.
6.3.8.5. Example: Define Errored Rows query where the errored all errored records in the
GL_INTERFACE have the value EM01 in the STATUS column.
6.3.8.5.1. Create a parameter list and add the first parameter which will contain the
following SQL statement in the Value field.
SELECT * FROM GL_INTERFACE WHERE REQUEST_ID = $PARAM$.request_id AND
STATUS = EM01
6.3.8.5.2. Add a parameter to the list for the request_id bind variable. Set name to
request_id. Set Attribute1 = BIND; Attribute2 = requested; Attribute3 = IMPORT;
Attribure5 = requested; Attribure6=NUMBER
6.3.9.2. Use the Add Another Row button to add the first parameter to the list. This
parameter is the SQL statement that is to be executed Use the following format for a
SQL statement: SELECT column_names FROM table_names WHERE column =
$PARAM$.parameter_name.
6.3.9.3. Create parameters in the list for each bind/return variable that exists in the SQL
statement.
The name of each parameter is used as the mapping between the SQL statement and
the bind/return variables. Make sure the parameter name in the SQL statement and
in the parameter use the same case.
SEQ_NUM 1
STRING_VALUE The SQL statement
PARAM_LIST_ID Parameter List ID created for the ERROR_LOOKUP step
SEQ_NUM N
PARAM_NAME Name of the bind/return parameters used in the SQL statement
73
Company Confidential - For internal use only
Column Name Description
6.3.9.4. Define attributes for each parameter in the list except the first. The details of the
parameters attributes are as follows:
6.3.9.5. Enter the parameter list ID created above into the value field in the
ERROR_LOOKUP step parameter in the master list. Make sure the Data Type is set to
number.
Sequence Number 1
Value SELECT MEANING FROM FND_LOOKUPS WHERE LOOKUP_TYPE =
PSP_SUSP_AC_ERRORS AND LOOKUP_CODE = $PARAM$.error_code
Data Type String
Sequence Number 2
Name Meaning
Data Type String
Sequence Number 3
Name error_code
Data Type String
Column DESCRIPTION
For the
error_code
parameter
74
Company Confidential - For internal use only
ATTRIBUTE1 BIND
ATTRIBUTE2 error_status
ATTRIBUTE3 INTERFACE_TABLE
ATTRIBUTE4 GL_INTERFACE. STATUS
ATTRIBUTE5 VARCHAR2
ATTRIBUTE6 1
The Cleanup SQL statement step defines the metadata required to run a SQL statement, but will only be
run when an exception occurs in one of the other import steps. If the SQL is a select statement then the
values that have been selected are saved to the IMPORT hash table. Bind variables can be used to define
what is used in the query and Return variables will be used to retrieve values from the SQL. Bind
variables are used in both SQL and Insert/Update statements to allow the statement to be defined
without knowing the data at design time. The return variables are only used in select statements, and
represent the columns in the select declaration. Return values are values from columns defined in the
select declaration section of the query (e.g. the status part of select status from gl_interface). The first
parameter in the list is the SQL statement that is to be executed and the rest of the parameters will
provide the details of the bind/return variables.
6.3.10.3. Use the Add Another Row button to add parameters to the list for every bind and
return variables defined in the SQL statement. The parameter name will be used as the
mapping between the SQL statement and the bind/return variables. In the above definition,
the $PARAM$.parameter_name will replaced with the value that is derived from the
metadata for the parameter in the parameter list with the name of parameter_name. This
method of replacing $PARAM$ tokens with the associated parameter values works for any
SQL statement not just select statements.
For select statements, the column_names will also need to be defined as parameters in the list
where the column_name will also be the name of the parameter. The values returned from the
columns in the select statement will be retrieved by going through the parameter list and for
every parameter that has ATTRIBUTE1=RETURN
75
Company Confidential - For internal use only
6.3.11. Cleanup PL/SQL API Call
The Cleanup PL/SQL API import step allows for a PL/SQL API to be called if an exception occurs in any
of the import steps. This step can be used to roll back work done in steps prior to the error. From the
metadata the PL/SQL API call will be dynamically generated and run. The first parameter in the
parameter list will define the API and the API calls parameters.
6.3.11.1. Create a parameter list using the Parameter UI. Set the Name of the parameter list to
(Integrator Name):CLEANUP_SQL .
6.3.11.2. Press Add Another Row to create the first parameter in the list. This parameter will
describe the API. Assign the following attributes to the parameter:
6.3.11.3. Add additional parameters to the list for each of the parameters within the API call.
Assign the following attributes to each parameter:
ATTRIBUTE9 is used to store a Parameter List ID to a parameter list where the parameters
provide a mapping between string values. E.g. A simple parameter list would convert
true/false into Y/N.
76
Company Confidential - For internal use only
ATTRIBUTE10 is used when the data provided needs to have some formatting applied before
it gets passed in as a parameter. This attribute should only be used in very rare cases. The
main case where this attribute would be used is for passing a DATE value from the import into
a PL/SQL API as a VARCHAR2 parameter. In the situation where a the date is required in
MM/ DD/YYYY format, the ATTRIBUTE10 value would be: TO_CHAR(?, MM/DD/YYYY)
77
Company Confidential - For internal use only
7. Defining Upload Parameters
Parameters that govern the upload process must be defined for every Integrator. These parameters can determine
what rows are uploaded, how they are pre-validated, and whether or not an import process is invoked. They
may also contain parameters required by your Integrators import program. Parameter values can be defaulted in
metadata; they can be passed to the create document service by the calling form function; others can be displayed
as options to users at runtime in the Upload Parameters screen.
The Upload Parameters screen is accessed by pressing Parameters after selecting Upload from the Oracle
menu. This screen presents users with options that affect how their data is uploaded to Oracle Applications.
Parameters are arranged vertically in a single column. Below is an example:
A parameter list will be created for an Integrator to define all the parameters that will be used for upload.
Some parameters will have default values and not be displayed in the Upload Parameters screen; others will
be defaulted but displayed. Parameter values can also be selected by users in the Upload Parameters screen.
The following steps cover the creation of an upload parameter list for your Integrator.
78
Company Confidential - For internal use only
A parameter list will be created that contains all upload parameters. Three specific parameters must
always be defined in an upload list, and others can be added that relate to the import program being
used.
7.2.1.1. Use the parameter list UI to define a parameter list. Use the Add Another Row
button to add the following parameters to the list:
Sequence 1
Definition Copy the 231:ROWS parameter definition under your
own application ID and use the copy for this
parameter.
Name Bne:rows
Value Y
Description True
Sequence 2
Definition Copy the 231:VALIDATION parameter definition
under your own application ID and use the copy for
this parameter.
Name Bne:validation
Value Y
Description True
Sequence 3
Definition Copy the 231:IMPORT parameter definition under
your own application ID and use the copy for this
parameter.
Name Bne:import
Value Y
Description True
7.2.1.2. Add additional parameters to the list if you have any parameters for your import
program that need to be chosen by the user at upload time, or just seen by the user as
upload time (view default being used). You may also define parameters and their
values that need to be passed to the import program that are not seen or displayed to
the user (not visible, but passed in the background).
7.2.1.2.1. Press the Definition button in the Define Parameter window to indicate more
information about each parameter. Tips:
Parameters in a list can be set so that they do are not displayed to users in the
upload parameters screen. Use the Default Required, Default Visible, and
Default user Modifiable checkboxes to determine how the parameter will be
displayed.
Parameters that rely on runtime data to determine whether or not to display can
be linked to a class that will set this value when run. Enter the class name in the
Java Processor Class field.
Display type indicates the type of widget to use in displaying the parameter to
users. Check Box, Radio Button, List Box, Text Box, and Password Field are the
supported display types.
Radio buttons and list boxes can retrieve their valid values from value sets or
from FND_LOOKUPS. Use the Validation Type field to indicate how the
parameter will be validated and enter the Value Set ID or
FND_LOOKUP.LOOKUP_TYPE in the validation value field.
Use the Display Style field to display radio buttons vertically or horizontally.
79
Company Confidential - For internal use only
7.2.2.1. Assign the parameter list to your Integrator by updating
BNE_INTEGRATORS_B.UPLOAD_PARAM_LIST with the parameter list ID created
in 7.2.1.1.
80
Company Confidential - For internal use only
8. Creating Content
Web ADI has the ability to import data into a document as it is being created on the desktop. Integrator
developers create Content definitions to identify the data to be downloaded, and any required parameters.
This data can come from a variety of sources.
Create a Java class to dynamically generate source data and provide custom UI for parameter entry.
This chapter section describes the process of enabling each of these types of Content in Web ADI metadata.
Attention: You must make sure that the code you plug into the Web ADI SDK is
functionally secure. Users must be prevented from manipulating a URL or a value in
the worksheet that would give them access to restricted values.
A SQL statement can be plugged into metadata that is run by Web ADI to retrieve a result set, which is
imported into the document using a mapping (maps fields in SQL statement to fields in document; see section
9.2). You may specify bind variables in the SQL statement, whose values can be passed at runtime. Each
Stored SQL statement requires a Content definition. Follow the steps below to define a stored SQL Content.
BNE_CONTENT_UTILS.CREATE_CONTENT_STORED_SQL
(P_APPLICATION_ID IN NUMBER,
P_OBJECT_CODE IN VARCHAR2,
P_INTEGRATOR_CODE IN VARCHAR2,
P_CONTENT_DESC IN VARCHAR2,
P_COL_LIST IN VARCHAR2,
P_QUERY IN VARCHAR2,
P_LANGUAGE IN VARCHAR2,
P_SOURCE_LANGUAGE IN VARCHAR2,
P_USER_ID IN NUMBER,
P_CONTENT_CODE OUT NOCOPY VARCHAR2);
Parameter Description
81
Company Confidential - For internal use only
Parameter Description
P_QUERY The SQL statement that will be run to generate the data to be
downloaded to the desktop. This SQL statement can contain
bind variables in the form of $PARAM$.ParameterName.
Example:
SELECT PERIOD_NAME, START_DATE, END_DATE FROM
GL_PERIOD_STATUSES WHERE START_DATE >=
$PARAM$.startDate AND END_DATE <= $PARAM$.endDate
P_CONTENT_CODE Out parameter that uniquely identifies the content. This is
generated based on P_OBJECT_CODE.
P_LANGUAGE Languge the P_CONTENT_DESC will be stored against.
P_SOURCE_LANG Languate P_CONTENT_DESC will be translated from.
P_USER_ID The ID of your Application will be used to populate the WHO columns
8.1.2.1. Use the Parameter UI to create a parameter list. Use the following format for a name:
(Integrator Name) Content: (Meaningful description).
8.1.2.2. Add a parameter to the list for every parameter that appears in the SQL. The name
of the parameter must exactly match the parameter name used in the SQL statement
(must also be in the same case).
8.1.2.2.1. Press the Definition button for each parameter to add details on how the
parameter will behave. Instructions entered into the user tip field will be displayed to
users who must enter a value for this parameter after choosing the Content. You can
indicate what UI widget web ADI will use to render the parameter value selection to the
user. The method in which the parameter value is validated is also indicated in this
parameter definition.
82
Company Confidential - For internal use only
Column Name Description
It is possible to import a text file into a document. Use the following steps to implement this type of Content
for your Integrator. Only one Text File Content needs to be created to allow users to import text files.
This package will create the content definition, parameter list and all of the content columns that will
be seen in the mapping UI.
Parameter Description
83
Company Confidential - For internal use only
8.3. Java
It is possible to create your own Content Class for download. This may be done if the simple UI
prompting users for parameter values required for download is inadequate. In addition, passing a SQL
statement, or plugging a SQL statement into metadata to generate a result set may not be viable options.
Steps to implement a Java Content:
Parameter Description
84
Company Confidential - For internal use only
8.3.3. Create Parameter List for Content
8.3.3.1. Use the Parameter UI to create a parameter list for the content. Add a parameter to
the list for every parameter required by the content class.
8.3.3.1.1. Press the definition button in the Define Parameter screen to determine how
these parameters will be selected by users in the Web ADI Create Document Page flow.
85
Company Confidential - For internal use only
9. Reporting Only Documents
It is possible to download Content to a document without giving users the ability to upload. When the
document is created, the Upload option in the Oracle menu will not appear. Layouts and Mappings based on
Interfaces designed for upload can be used to generate reporting documents. Alternatively, Reporting only
documents can be created with Interfaces and Mappings specifically made for Reporting and do not have the
ability to facilitate Upload.
The Interfaces, Layouts and Mappings that have been created for uploading data can be used to generate
Reporting Only documents. This can be done by setting the bne:reporting parameter to Y when the Web
ADI service is called. This parameter is displayed in the Web ADI Pageflow as Reporting Only. If the box
is checked, then the document you create will not have the upload option.
Interfaces, Mappings and Layouts can be flagged as reporting only. This means that regardless of the
bne:reporting parameter value, when a layout is selected that is based on a Reporting Interface, the resulting
document will always be generated without the upload option. This method of providing reporting
documents can be used when you simply want to download Content to a document that will never be
uploaded. To enable users to download a Content for reporting purposes:
9.2.1. Run the Following API to create an Interface and Mapping based on the Content.
BNE_CONTENT_UTILS. ENABLE_CONTENT_FOR_REPORTING
(P_APPLICATION_ID IN NUMBER,
P_OBJECT_CODE IN VARCHAR2,
P_INTEGRATOR_CODE IN VARCHAR2,
P_CONTENT_CODE IN VARCHAR2,
P_LANGUAGE IN VARCHAR2,
P_SOURCE_LANGUAGE IN VARCHAR2,
P_USER_ID IN NUMBER,
P_INTERFACE_CODE OUT NOCOPY VARCHAR2,
P_MAPPING_CODE OUT NOCOPY VARCHAR2);
Parameter Description
The name of the Interface that is created will be {Content Name} Reporting Interface. The name of the
Mapping that is created will be {Content Name} Reporting Mapping.
9.2.2. Once the API has been run, Layouts can be created for a reporting Interface that will allow
users to create their documents.
86
Company Confidential - For internal use only
10. Creating Layouts and Mappings
10.1. Creating Layouts
A Layout is a parameter given to the Create document service that indicates what columns are to be included
in a document. The placement of these columns within the document is also indicated by the Layout.
Layouts can be seeded with your application. Layouts can be defined to create documents that do not offer
upload, in addition to ones that provide upload capability. UI exists for Layout creation:
10.1.3. The following screen shows all of the Layouts that have been defined for an Integrator. The
Reporting column indicates layouts that can only be used to create document that do not provide
upload. Press Define Layout to create a new layout, or update, duplicate or delete existing
layouts.
10.1.4. Enter a Name and Key for your Layout and select a Field List. The Key is a unique code that
that is used to reference the Layout when calling the BneApplicationService. It must be a string of
20 characters or less. The only valid characters are: Uppercase 'A'..'Z', '0'..'9' and '_'.
10.1.5. Select a Field List. The Field list selection determines the group of columns available to you
when determining which columns to include in your Layout. It also determines whether or not
your Layout can be used to create a document for upload purposes. The first selection in the drop
down box will allow a Layout to be generated for upload. This Field list contains all of the columns
87
Company Confidential - For internal use only
defined for Interfaces created for upload (BNE_INTERFACES_B.UPLOAD_TYPE = 1). All of the
other values in the LOV provide lists of columns that can be used to create Layouts that do not offer
upload.
10.1.7. Select the optional fields to be included in the Layout and their location (header/Lines).
Note: UI does not exist to define the column order in the document when a particular Layout is
used. Update BNE LAYOUT COLS.SEQUENCE NUM to accomplish this.
88
Company Confidential - For internal use only
10.1.8. Enter default values you would like to automatically appear for columns when the document
is created. There are five types of defaults you may set:
10.1.8.1. None Default Type when no Default Value is set.
10.1.8.2. Constant - Default Type used when the actual value in Default Value is used as the
default.
10.1.8.3. Environment Default Type when Default Value is an environmental variable. Valid
environmental variables are: language, oauser.id, database, sob.SetOfBooksName, and
sysdate., sob.setofbooksname, sob.setofbooksid, sob.chartofaccountsid, sob.periodsetname,
sob.accountedperiodtype, sob.currencycode, sob.latestencumbranceyear, sob.adbflag,
sob.consolidationflag, sob.transactioncalendarid, sob.mandate, sob.maxdate
10.1.8.4. Parameter Default type when Default Value is the name of a parameter passed to
BneApplicaionService.
10.1.8.5. SQL Default Type used when a SQL statement is entered into Default Value. Web
ADI will run this SQL and automatically populate the document with the result. If more than
one value is returned from the query, the first value returned will be used. You may use the
following tokens in the SQL statement entered in Default Value:
$profile$.profileName
$env$.userid
$env$.appid
$env$.respid
$env$.language
A Mapping links Content columns to Interface columns. This relationship between the columns in the result
set of a download and the destination column is needed for Web ADI to import data into the document.
UI exists for Mapping Creation (Note that Mappings for reporting Interfaces are not created through the
Mapping UI, but are created by the API in section 9.2):
10.2.3. Select the Content you wish to map and press GO. This screen will not appear if you only
one Content exists for the chosen Integrator.
89
Company Confidential - For internal use only
10.2.4. Press Define Mapping or update, duplicate or delete an existing Mapping.
10.2.5. Enter a Name and Key for your Mapping and the number of columns it will Map. The Key is
a unique code that is used to reference the Mapping when calling the BneApplicationService. It can
be a string of 20 chars or less. The only valid characters are: Uppercase 'A'..'Z', '0'..'9' and '_'.
10.2.6. Use the LOVs to match Content columns with Interface columns. Press Apply when
finished.
90
Company Confidential - For internal use only
91
Company Confidential - For internal use only
11. Calling the Create Doc Page Flow
The create document page flow can be called from either a pre defined form-function on the PHP, or from
within a Self Service Application. The oracle.apps.bne.webui.BneApplicationService servlet is called to
invoke the create document process. It may be called with the parameters described in this chapter.
If a required parameter is not supplied, UI will be displayed to prompt users for a value. Supplied
parameters will be validated by the page flow when it is initialized, and any parameters that are in error will
need to be reselected by the user at run time. If all of the parameters are correct, the user will see either the
Review page, or if bne:noreview is supplied, the document will be created immediately.
Note that bne:page=BneCreateDoc must be used to invoke the create document process. All
other parameters may not be set in the call, but can be left for users to choose at runtime through
the Create Document UI.
Bne:map is also required if a Content other than None is selected. This parameter points to a mapping
defined in metadata that relates source and destination columns.
Content Parameters Any of the parameters defined in the parameter list associated with the
content being passed. The list is identified in
BNE_CONTENTS_B.PARAM_LIST_CODE. Look up this parameter list
in the Parameter UI to get a list of available parameters.
bne:map This parameter is dependent on the content. It specifies the mapping to
92
Company Confidential - For internal use only
Parameter Required Description
be used for download. The value of this parameter must be in the form
of Application ID:Mapping Code.. E.g.
bne:map=231:INTERFACE_TABLE_MAP
bne:redirect-portal A URL to redirect the user to after the Viewer has been created. If this is
not supplied, the user will be redirected to their personal home page.
The value can be any valid URL starting with http:// or https://
Example: bne:redirect-portal=http://www.oracle.com.
bne:noreview If this parameter is sent with any value the Create Document Review
page will not be displayed. Example: bne:noreview=anything
The upload parameters you have defined for your Integrator may be passed to the document creation
service. Use the value in BNE_INTEGRATORS_B.UPLOAD_PARAM_LIST_CODE and
UPLOAD_PARAM_LIST_APP_ID for your Integrator to view the required list of parameters in the
parameter UI. To pass an upload parameter you have to provide values that are correct for the
parameter. Then you can add the parameter to the URL as &<paramName>=<paramValue>
Example:
http://adi.us.oracle.com/servlets/oracle.apps.bne.webui.BneApplicationService?bne:page=BneCreateD
oc&bne:language=US&bne:rows=FLAGGED&bne:validation=NONE&bne:import=false
http://adi.us.oracle.com/servlets/oracle.apps.bne.webui.BneApplicationService?bne:page=BneCreateD
oc&bne:language=US&bne:param-list=231:LIST_ON
As long as the passed parameter is defined in UPLOAD_PARAM_LIST_CODE tied to the Integrator and
has a valid value, that value will be used as an upload parameter, and not the default value defined in
metadata. The passed parameters are stored in the worksheet. Therefore, the passed parameters will be
used even if user saves the sheet, logs out of Self-Service and uploads at a later time.
Core parameters are sent on the HTTP command line in three different ways:
Content and Upload parameters are defined by the Integrator developer and are sent in the form of
name=value&name=value.
Example:
93
Company Confidential - For internal use only
http://adcsrv06.au.au.oracle.com:8080/servlet/BneApplicationService?bne:page=BneCreateDoc&bne:lan
guage=US&bne:viewer=231:EXCEL2000&bne:integrator=BNE:JOURNALS_115&bne:layout=231:FUNC
T_ACT_SINGLE&bne:content=231:ADDRESS&firstname=Jim
SQL wild cards are supported for Codes and USER_NAME values. E.g. bne:layout=BNE:USER%. If a
Wild Card returns one parameter value, then users will not be prompted to select that value in the Create
Document Page Flow. If multiple parameter values are returned, users will be prompted to select a value
from the filtered list. Note: Wildcards cannot be used for Application IDs or Application Short Names.
Profile options and environmental variables can be referenced when sending parameter values to
BneApplicationService. The formats to use when referencing profile options and environmental variables
are $Env$.variable_name and $Profiles$.profile_name respectively. For example, Web ADI will reference
profile option XXXX for the current applications user to resolve the Integrator value when
bne:integrator=231:$Profiles$.XXXX is passed. You must make sure the resolved parameter value
conforms to one of the three different parameter standards mentioned earlier in this section.
The ASCII characters 'a' through 'z', 'A' through 'Z', '0' through '9', and ".", "-", "*", "_" remain the same.
The space character ' ' is converted into a plus sign '+'.
All other characters are converted into the 3-character string "%xy", where xy is the two-digit
hexadecimal representation of the lower 8-bits of the character.
If you are sending from a HTML form, this is done for you. If it is seeded in a form-function, strings
with the % wildcard and URLS (in bne:redirect-portal) need attention.
Example:
bne:language Am%
be:layout 231:FUNCT_ACT
94
Company Confidential - For internal use only
http://adi.us.oracle.com/servlet/oracle.apps.bne.webui.BneApplicationService?bne:page=BneCreateDoc&
bne:language=Am%25&bne:layout=231:FUNCT_ACT&bne:redirect-
portal=http%3A%2F%2Fwww.google.com%2Fsearch%3Fsourceid%3Dnavclient%26q%3Dservlet+redire
ct+http
% --> %25, : --> %3A, / --> %2F, ? --> %3F, = --> %3D, & --> %26, space --> +
If data is POSTed to BneApplicationService (ie a HTML for that does a POST), large amounts of data may
be sent to us.
If data is GETed to BneApplicationService (A GET is performed when a URL is entered directly into the
IE Address line, when an HTML form calls BneApplicaitonService, and when a Self-Service form function
calles BneApplicaitonService), then you are limited to a total address length of about 1800 characters.
This is a browser restriction.
Any parameters in the list will over-ride parameters sent on the http command line.
Example:
http://adi.us.oracle.com:8080/servlet/oracle.apps.bne.webui.BneApplicationService?bne:page=BneCreate
Doc&bne:language=US&bne:param-list=SQLGL:F_SINGLE_JNL_FR
If the F_SINGLE_JNL_FR Parameter List has a parameter bne:language=FR, then the value used is FR.
At the end of the Create Document Page flow, users are presented with the option of saving a document
creation shortcut. Shortcuts can be saved in two ways:
Selections are saved to shortcut that will appear on the first page of the Create Document Page
Flow. All users must do is select the shortcut, and all of their saved parameter values will be
used to generate a document.
Selections are saved to a Self-Service Form Function. The name you enter for the shortcut will be
used to create the Function Name and User Function Name (BNE_Shortcut Name). A system
administrator must search for this form function and attach it to a menu so it appears in the PHP.
95
Company Confidential - For internal use only
Only the core and content specific parameters are saved as document creation shortcuts. bne:redirect-
portal, bne:review, bne:param-list or passthrough params are not saved. This is because of a limit to the
amount of data that can be saved to a self-service menu item.
96
Company Confidential - For internal use only
APPENDIX A Parameter UI
Parameter UI was included with Web ADI 8.2. This allows you to quickly create, duplicate, and delete,
Parameter Lists, Parameter List Items, Parameter Definitions and Attributes.
Accessing Parameter UI
1. Click on the Create Doc link from the Web ADI menu.
2. Replace BneCreateDoc with BneParameter
3. The Define Parameter List page should be displayed.
4. This can also be imbedded in the form function on your Self-Service page. Log into Applications as
System Administrtor. Navigate to Applicaton=>Function and create a new form function with the
following values:
Field Value
Function BNE_DEFINE_PARAMS
Type SSWA SERVLET
Parameters Bne:page=BneParameter
HTML Call oracle.apps.bne.webui.BneApplicationService
NOTE: the Parameter List Code is displayed at the top of the page once
the Parameter List has been saved.
To add Parameters to the Parameter List, click on the Add Another Row button in the Parameters table at the
bottom of the Define Parameter List page.
1. Enter a meaningful Name for the Parameter. If creating a parameter list for a component, see the list of
parameters to add to the parameter list in section 5.1.4.
2. Enter values for all other fields. All three values: Data Type, Value, and Description must be entered,
either all three against the Parameter, or all three against the Parameter Definition. Values entered against
the Parameter will take precedence over values entered against the Parameter Definition. Data Type must be
String if you are defining a component for a parameter.
3. Click on the Save button.
4. To save the Parameter in the List, and to save these changes to the database, click the Save button at the
bottom of the Define Parameter List page.
To define a new Parameter Definition, click on the Definition button at the bottom of the Define Parameter
page.
97
Company Confidential - For internal use only
1. Enter a meaningful Name, Code, and Source.
2. Enter a Data Type, Default Value and Default Description. All three values: Data Type, Default Value,
and Default Description must be entered, either all three against the Parameter, or all three against the
Parameter Definition. Values entered against the Parameter will take precedence over values entered against
the Parameter Definition. For all Component Parameters, a Data Type of String MUST be used.
3. Select a Category that is relevant to the Parameter being defined.
4. Once all values have been entered, click the Save button.
1. Click on the Search Light icon next to the Parameter Definition label on the Define Parameter page.
2. After selecting the Parameter Definition from the displayed list, click on the Save button.
3. To save this change to the database, click on the Save button on the bottom of the Define Parameter List
page.
Click on the Apply button after entering valid values. If you are returned to the Define Parameter List page,
your parameter list items has been correctly defined. Otherwise, an error message is displayed.
Press the Reset button to reset the Parameter List items to their default values for more testing.
98
Company Confidential - For internal use only
APPENDIX B Shipping Your Integrator
Web ADI metadata can be extracted out of your seed instance and delivered as part of a patch to customers. All
objects created in metadata are striped by Application ID and are uniquely identified by a combination of
Application ID & Code. To prevent conflicts, you must only extract and ship metadata under your products
Application ID. It is the responsibility of product owners to prevent duplicate codes for the same object (e.g.
layouts, mappings) from being shipped within the same Application ID.
Applications 11i
Ldt files containing the metadata are generated using FNDLOAD. The control files that are required to generate
the ldts are included in the Web ADI 8.3 patch. The following are the available lcts that can be used to
export/import your metadata:
bnecomp.lct Components
bnecont.lct Contents
bneint.lct Integrators
bnelay.lct Layouts
bnemap.lct Mappings
bness.lct Stylesheets
bnevw.lct Viewers
The following lcts are available but are generally not used for extraction because they relate to runtime
information:
bnefile.lct Extracts data describing text files that have been uploaded to the middle tier.
Applications 12
As of R12, Web ADI is shipping all of its metadata using a single lct file located under
$BNE_TOP/patch/115/import/bneintegrator.lct. We recommend all teams to use this lct file starting in R12. All new
features will be made available in the lct file only, and not dual maintained in the old lct files. The header of this lct file is
reproduced below, it contains instructions on how to use it to extract metadata for including in a patch.
# FILENAME
# bneintegrator.lct
#
# DESCRIPTION
99
Company Confidential - For internal use only
# Loader DOWNLOAD/UPLOAD configuration file for all INTEGRATOR related data.
# Using this lct file with one DOWNLOAD command, you should be able to download
# everything required for a Web ADI Integrator to run.
# @since R12
#
# NOTES
# It is STRONGLY recommended that project teams download data using only the BNE_INTEGRATORS entity
# and not piecemeal (as has been done in the past). This will produce a single ldt file per
integrator,
# or many integrators per ldt file.
#
# Download your integrator as follows:
# - All Integrators for an application:
# $ FNDLOAD apps/apps 0 Y DOWNLOAD bneintegrator.lct bneintegrators.ldt BNE_INTEGRATORS
INTEGRATOR_ASN=BNE
#
# - A specific Integrator:
# $ FNDLOAD apps/apps 0 Y DOWNLOAD bneintegrator.lct bneNewMsgs.ldt BNE_INTEGRATORS
INTEGRATOR_ASN=BNE INTEGRATOR_CODE=FND_NEW_MESSAGES_INTG
#
# - Two Integrators:
# $ FNDLOAD apps/apps 0 Y DOWNLOAD bneintegrator.lct bneNewMsgs.ldt BNE_INTEGRATORS
INTEGRATOR_ASN=BNE INTEGRATOR_CODE_LIST=FND_NEW_MESSAGES_INTG,JOURNALS_115
#
# If you have problems with this script, log a bug against product BNE (bugId 1171), component INSTALL
#
# ENTITIES AND PARAMETERS
# BNE_INTEGRATORS
# INTEGRATOR_ASN : Integrator Application Short Name
# INTEGRATOR_CODE : Integrator Code
# or
# INTEGRATOR_CODE_LIST: A comma separated list of integrator codes (without wildcards).
#
# Note: You should only use one of the INTEGRATOR_CODE and INTEGRATOR_CODE_LIST parameters at one
time.
# Note: Due to the way the DOWNLOAD section works, it is possible to download multiple integrators if
one
# integrator code is a substring of another.
# Code >> :INTEGRATOR_CODE_LIST is not null AND instr(:INTEGRATOR_CODE_LIST, V.INTEGRATOR_CODE)
> 0)
# will match INTEGRATOR_CODE XYZ_INTEG and XYZ_INT when using INTEGRATOR_CODE_LIST
XYZ_INTEG01,XYZ_INTEG02
# Please be aware of this when downloading entities.
#
#
# BNE_QUERIES
# QUERY_ASN : Query Application Short Name
# QUERY_CODE : Query Code
#
# BNE_PARAM_LISTS
# PARAM_LIST_ASN : Parameter Application Short Name
# PARAM_LIST_CODE : Parameter List Code
#
# BNE_COMPONENTS
# COMPONENT_ASN : Component Application Short Name
# COMPONENT_CODE : Component List Code
#
# BNE_SECURED_OBJECTS
# SECURED_OBJECT_ASN : Secured object application short name
# SECURED_OBJECT_CODE : Secured object code short name
# SECURED_OBJECT_TYPE : Secured object type.
#
# BNE_VIEWERS
# VIEWER_ASN : Viewer Application Short Name
# VIEWER_CODE : Viewer Code
#
# The following entity is internal to the Web ADI project team. DO NOT USE IT.
# All menu entries for an Integrator will be exported with the integrator
# using the BNE_INTEGRATORS entity.
# ENTITY BNE_ROOT_MENUS
# MENU_ASN : Menu Application Short Name
# MENU_CODE : Menu Code
#
# All entities in this file are related as shown (entities with a * may be DOWNLOADED separately),
# not all FKs are shown for brevity:
#
# ENTITIES
# * BNE_INTEGRATORS
# |
# +-<BNE_GRAPHS
# | |
# | +-<BNE_GRAPH_COLUMNS
# |
# +-<BNE_INTEGRATOR_VIEWERS
# |
# +-<BNE_IMPORT_PROGRAMS
100
Company Confidential - For internal use only
# |
# +-<BNE_INTERFACES
# | |
# | +-<BNE_INTERFACE_COLS
# | |
# | +-<BNE_INTERFACE_KEYS
# | |
# | +-<BNE_INTERFACE_KEY_COLS
# |
# +-<BNE_DUPLICATE_PROFILES
# | |
# | +-<BNE_DUP_INTERFACE_PROFILES
# | |
# | +-<BNE_DUP_INTERFACE_COLS
# |
# +-<BNE_CONTENTS
# | |
# | +-<BNE_CONTENT_COLS
# | |
# | +--BNE_STORED_SQL >--BNE_QUERIES
# |
# +-<BNE_MAPPINGS
# | |
# | +-<BNE_MAPPING_LINES
# |
# +-<BNE_LAYOUTS
# |
# +-<BNE_LAYOUT_BLOCKS
# |
# +-<BNE_LAYOUT_COLS
#
# * BNE_COMPONENTS
#
# * BNE_QUERIES
# |
# +--BNE_SIMPLE_QUERY
# |
# +-<BNE_RAW_QUERY
#
#
# * BNE_PARAM_LISTS>---------------+
# | |
# +-<BNE_PARAM_GROUPS |
# | | |
# | +-<BNE_PARAM_GROUP_ITEMS>-+--BNE_ATTRIBUTES
# | V |
# +-<BNE_PARAM_LIST_ITEMS>------+
# V |
# +--BNE_PARAM_DEFNS>-------+
# |
# +-<BNE_PARAM_OVERRIDES
#
# * BNE_SECURED_OBJECTS
# V
# +--BNE_SECURITY_RULES
#
# * BNE_ROOT_MENUS
#
# * BNE_VIEWERS
101
Company Confidential - For internal use only
APPENDIX C - Sample Code
Sample SQL Class - BneOAPeriodNameSQL (GL Journals Period Name LOV/Validator)
/*
* +=======================================================================+
* | Copyright (c) 2003 Oracle Corporation, Redwood Shores, CA, USA |
* | All rights reserved. |
* +=======================================================================+
* | HISTORY |
* | |
* | 27-Jun-2003 John Smith Created. |
* | |
* +=======================================================================+
*/
package oracle.apps.bne.utilities.oa;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;
import oracle.apps.bne.exception.BneException;
import oracle.apps.bne.framework.BneTrace;
import oracle.apps.bne.framework.BneWebAppsContext;
import oracle.apps.bne.utilities.sql.BneBaseSQL;
import oracle.apps.fnd.common.VersionInfo;
/**
* Class BneOAPeriodNameSQL
* <p>
* This class contains all of the SQL queries required for the Period Name
* LOV and Upload validation.
*
* @author John Smith
* @version $Revision: $ $Date: $
*/
// Field RCS_ID_RECORDED
public final static boolean RCS_ID_RECORDED =
VersionInfo.recordClassVersion(RCS_ID, "oracle.apps.bne.utilities.oa");
/**
* Method: BneOAPeriodNameSQL
* <p>
* Construct the object.
* You must call super() within this constructor.
* To properly destruct this object and clean up any cursors YOU MUST run close();
*
* @param context - This is all the session information for the current user
session.
* @param queryNumber - The number identifying the query to be used to create the
SQL Handle.
* Valid query numbers are:
* 1 - query to retrieve all open and future enterable budget
periods.
* 2 - query to retrieve all open and future enterable
periods containing a specific
* date (Actual Journals only)
* 3 - query to retrieve all open and future enterable
periods (Actual Journals only)
* 4 - query to retrieve all open and future enterable
periods containing a specific
102
Company Confidential - For internal use only
* date (Encumbrance Journals only)
* 5 - query to retrieve all open and future enterable
periods (Encumbrance Journals only)
* @param extraSQL - The string to contain the additional SQL criteria to limit
the SQL result
* set to the value selected by the user in the Web ADI
document. When calling the
* constructor for the LOV component, pass null to this
parameter.
*
* @throws SQLException on any SQL problem.
* @throws BneException on any internal WebADI problem.
*/
public BneOAPeriodNameSQL(BneWebAppsContext context, int queryNumber, String
extraSQL)
throws SQLException, BneException
{
super();
if (context == null)
{
throw new IllegalArgumentException("BneOAPeriodNameSQL - parameter:
context, a valid context must be passed to this constructor.");
}
switch ( queryNumber )
{
case 1:
qry.append("SELECT DISTINCT PS.PERIOD_NAME, PS.PERIOD_YEAR,
PS.PERIOD_NUM " +
"FROM GL_PERIOD_STATUSES PS, GL_BUDGET_PERIOD_RANGES BPR,
GL_BUDGET_VERSIONS BV, GL_BUDGETS B " +
"WHERE B.SET_OF_BOOKS_ID = ? " +
"AND BV.BUDGET_VERSION_ID = ? " +
"AND B.BUDGET_NAME = BV.BUDGET_NAME " +
"AND BV.BUDGET_VERSION_ID = BPR.BUDGET_VERSION_ID " +
"AND BPR.PERIOD_YEAR = PS.PERIOD_YEAR " +
"AND PS.PERIOD_NUM BETWEEN BPR.START_PERIOD_NUM AND
BPR.END_PERIOD_NUM " +
"AND BV.BUDGET_TYPE = B.BUDGET_TYPE " +
"AND UPPER(B.BUDGET_TYPE) = 'STANDARD' " +
"AND PS.SET_OF_BOOKS_ID = ? " +
"AND PS.APPLICATION_ID = 101 " +
"AND PS.PERIOD_TYPE = ? " +
"AND PS.PERIOD_YEAR <= B.LATEST_OPENED_YEAR " +
"AND PS.ADJUSTMENT_PERIOD_FLAG = 'N' ");
break;
case 2:
qry.append("SELECT PS.PERIOD_NAME, PS.START_DATE, PS.END_DATE,
PS.PERIOD_NUM, PS.PERIOD_YEAR " +
"FROM GL_PERIOD_STATUSES_ACTUAL_V PS " +
"WHERE PS.SET_OF_BOOKS_ID = ? " +
"AND TRUNC(PS.START_DATE) <= TRUNC(?) " +
"AND TRUNC(PS.END_DATE) >= TRUNC(?) ");
break;
case 3:
qry.append("SELECT PS.PERIOD_NAME, PS.START_DATE, PS.END_DATE,
PS.PERIOD_NUM, PS.PERIOD_YEAR " +
"FROM GL_PERIOD_STATUSES_ACTUAL_V PS " +
"WHERE PS.SET_OF_BOOKS_ID = ? ");
break;
case 4:
qry.append("SELECT PS.PERIOD_NAME, PS.START_DATE, PS.END_DATE,
PS.PERIOD_NUM, PS.PERIOD_YEAR " +
"FROM GL_PERIOD_STATUSES_ENC_V PS " +
"WHERE PS.SET_OF_BOOKS_ID = ? " +
"AND TRUNC(PS.START_DATE) <= TRUNC(?) " +
"AND TRUNC(PS.END_DATE) >= TRUNC(?) ");
break;
103
Company Confidential - For internal use only
case 5:
qry.append("SELECT PS.PERIOD_NAME, PS.START_DATE, PS.END_DATE,
PS.PERIOD_NUM, PS.PERIOD_YEAR " +
"FROM GL_PERIOD_STATUSES_ENC_V PS " +
"WHERE PS.SET_OF_BOOKS_ID = ? ");
break;
default:
throw new IllegalArgumentException("BneOAPeriodNameSQL - parameter:
queryNumber, must be a number from 1 to 5.");
}
package oracle.apps.bne.integrator.validators.gl;
import java.sql.Date;
import java.sql.SQLException;
import java.sql.Timestamp;
import java.text.SimpleDateFormat;
import java.util.Enumeration;
import java.util.Hashtable;
import oracle.apps.bne.exception.BneException;
import oracle.apps.bne.exception.BneFatalException;
import oracle.apps.bne.exception.BneMissingParameterException;
import oracle.apps.bne.exception.BneSQLException;
import oracle.apps.bne.framework.BneConstants;
import oracle.apps.bne.framework.BneLogger;
import oracle.apps.bne.framework.BneTechStack;
import oracle.apps.bne.framework.BneTrace;
import oracle.apps.bne.framework.BneWebAppsContext;
import oracle.apps.bne.integrator.upload.BneUploadColumn;
import oracle.apps.bne.integrator.upload.BneUploaderMessage;
import oracle.apps.bne.integrator.validators.BneUploadValidator;
import oracle.apps.bne.repository.BneResourceString;
104
Company Confidential - For internal use only
import oracle.apps.bne.utilities.BneStringUtils;
import oracle.apps.bne.utilities.oa.BneOACurrencyCodeSQL;
import oracle.apps.bne.utilities.oa.BneOAPeriodNameSQL;
import oracle.apps.bne.utilities.oa.BneSOBDetails;
import oracle.apps.bne.utilities.sql.BneCompositeSQLCriteria;
import oracle.apps.bne.utilities.sql.BneSQLStatement;
import oracle.apps.bne.utilities.sql.BneResultSet;
import oracle.apps.fnd.common.VersionInfo;
/**
* Class BneOAPeriodNameValidator
* <p>
* Implementation of BneUploadValidatorInterface and BneUploadDomainInterface
* for the Period Name interface column for the "General Ledger - Journals"
* Integrator.
* <p>
* The implementation of the BneUploadValidatorInterface validates the
* Period Name interface column.
* <p>
* The implementation of the BneUploadDomainInterface generates a List of Values
* for the Period Name interface column.
*
* @author John Smith
* @version $Revision: $ $Date: $
*/
/**
* RCS version insertion into <code>VersionInfo</code> on class loading.
*/
public static final boolean RCS_ID_RECORDED = VersionInfo.recordClassVersion(RCS_ID,
"oracle.apps.bne.integrator.validators.gl");
// The following constants refer to each of the SQL queries that exist in the
BneOAPeriodNameSQL class.
public static final int BUD_JOURNAL_NO_ACCT_DATE = 1;
public static final int ACT_JOURNAL_WITH_ACCT_DATE = 2;
public static final int ACT_JOURNAL_NO_ACCT_DATE = 3;
public static final int ENC_JOURNAL_WITH_ACCT_DATE = 4;
public static final int ENC_JOURNAL_NO_ACCT_DATE = 5;
// Logger to be used as needed. All log messages will be written to the bne.log file.
These messages
// will NOT be transalated, and are to be used for debugging purposes only.
private BneLogger m_Logger = BneLogger.getInstance();
/**
* Method: startupValidator
*
* This method initializes the SQL statement cache for the Period Name validator.
*
* @param context - All the valid session information for the current user session.
* @param requestParameters - A hashtable containing the document and upload page
parameters and
* their associated values.
* @param columnValues - A hashtable containing all the values for the current upload
row in the spreadsheet.
* @return Any relevant upload messages.
*/
public BneUploaderMessage [] startupValidator(BneWebAppsContext context,
Hashtable requestParameters,
Hashtable columnValues)
{
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.startupValidator() Start");
m_Statements = new Hashtable(); // Initialise the SQL statement cache.
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.startupValidator() End");
return (new BneUploaderMessage [0]);
105
Company Confidential - For internal use only
}
/**
* Method: getDomainParameters
*
* <p>Get the domain parameters. This is the union of all parameters that will be
used for the LOV Component.
*/
public String[] getDomainParameters ()
{
return(new String[] {"SET_OF_BOOKS_ID",
"ACTUAL_FLAG",
"ACCOUNTING_DATE",
"BUDGET_VERSION_ID",
"PERIOD_NAME"});
}
/**
* Method: getDomainValues
*
* <p>This method gets the values to be displayed in the Period Name Cabo/UIX LOV
page.
*
* <p>The following parameters are used within this method:
*
* SET_OF_BOOKS_ID
* ACTUAL_FLAG
* ACCOUNTING_DATE
* BUDGET_VERSION_ID
* PERIOD_NAME
* Period Type - this is derived from the Set of Books Details record.
*
* <p>
* Period Name LOV and Validation for Actual and Encumbrance Journals is only
available for
* Oracle Applications 11i and above.
*
* @param context - All the valid session information for the current user session.
* @param columnValues - A hashtable containing all the values for the current row in
the spreadsheet.
* @param criteria - All the details for the Period Name LOV component.
*
* @return SQL result set of Periods
*
* @throws BneException
*
*/
public BneResultSet getDomainValues (BneWebAppsContext context,
Hashtable columnValues,
BneCompositeSQLCriteria criteria) throws
BneException
{
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.getDomainValues() Start");
// If the user has entered criteria in the filter fields on the LOV page,
// add this restriction to the query by placing it in the extraSQL parameter
// which will be passed to the BneOAPeriodNameSQL constructor.
if (criteria != null)
{
106
Company Confidential - For internal use only
extraSQL = criteria.evaluate(extraSQL);
}
if (actualFlag == null)
{
throw new
BneMissingParameterException(BneResourceString.getMlsString("LOV_NO_ACTUAL_FLAG"));
}
if (sobIDString == null)
{
throw new
BneMissingParameterException(BneResourceString.getMlsString("UPL_ER_NO_SOB"));
}
else
{
setOfBooksId = Long.parseLong(sobIDString);
}
// Get all the Set of Books information for the current user.
BneSOBDetails sob = BneSOBDetails.getSOBDetails(context);
// Confirm the Set of Books in the spreadsheet matches the current user's Set of
Books.
if (setOfBooksId != sob.getSetOfBooksID())
{
throw new
BneMissingParameterException(BneResourceString.getMlsString("UPL_ER_SOB_MATCH"));
}
budgetVersionId =
Long.parseLong(BneOACurrencyCodeSQL.getBudgetId(context, budgetString));
} catch (SQLException e)
{
String errMsg =
BneResourceString.getMlsString("UPL_ER_BUDGET_VERSION_ID");
m_Logger.log(BneTrace.TRACE,
"BneOAPeriodNameValidator.getDomainValues() Error retrieving budget version Id " +
e);
throw new BneSQLException(errMsg, e);
}
}
try
{
107
Company Confidential - For internal use only
SQLHandle = new BneOAPeriodNameSQL(context, BUD_JOURNAL_NO_ACCT_DATE,
extraSQL.getStatement());
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.getDomainValues()
SQLHandle created to Budget Query.");
BneSQLStatement sqlStmt = new BneSQLStatement(SQLHandle.getQuery(),
new Object []{ new Long(setOfBooksId), new Long
(budgetVersionId),
new Long(setOfBooksId),
accountedPeriodType });
sqlStmt.append("", extraSQL.getBindValues());
rs = SQLHandle.getBneResultSet(sqlStmt.getBindValuesAsArray());
} catch (Exception e)
{
throw new BneFatalException (e.toString());
}
}
// Check that this is an 11i instance - Period Name support is only available for
Actual and Encumbrance
// journals in Applications 11i and above.
m_Logger.log(BneTrace.TRACE,
"BneOAPeriodNameValidator.getDomainValues() SQLHandle created to +
Actual Query - no Accounting Date in
spreadsheet.");
}
else
{
SQLHandle = new BneOAPeriodNameSQL(context,
ENC_JOURNAL_NO_ACCT_DATE, extraSQL.getStatement());
m_Logger.log(BneTrace.TRACE,
"BneOAPeriodNameValidator.getDomainValues() SQLHandle created to +
Encumbrance Query - no Accounting
Date in spreadsheet.");
}
BneSQLStatement sqlStmt = new BneSQLStatement(SQLHandle.getQuery(),
new Object []{ new Long(setOfBooksId) });
sqlStmt.append("", extraSQL.getBindValues());
rs = SQLHandle.getBneResultSet(sqlStmt.getBindValuesAsArray());
}
else
// If an Accounting Date has been entered in the spreadsheet by the user,
then the LOV is limited to
// Periods that contain the Accounting Date.
{
java.util.Date utilDate = tempDateFormat.parse(tempAccountingDate);
accountingDate = new java.sql.Date(utilDate.getTime());
if ("A".equals(actualFlag))
{
SQLHandle = new BneOAPeriodNameSQL(context,
ACT_JOURNAL_WITH_ACCT_DATE, extraSQL.getStatement());
m_Logger.log(BneTrace.TRACE,
"BneOAPeriodNameValidator.getDomainValues() SQLHandle created to Actual +
Query - limit by Accounting Date.");
108
Company Confidential - For internal use only
}
else
{
SQLHandle = new BneOAPeriodNameSQL(context,
ENC_JOURNAL_WITH_ACCT_DATE, extraSQL.getStatement());
m_Logger.log(BneTrace.TRACE,
"BneOAPeriodNameValidator.getDomainValues() SQLHandle created to +
Encumbrance Query - limit by
Accounting Date.");
}
sqlStmt.append("", extraSQL.getBindValues());
rs = SQLHandle.getBneResultSet(sqlStmt.getBindValuesAsArray());
}
} catch (Exception e)
{
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.getDomainValues()
Caught unknown exception: " + e);
throw new BneFatalException (e.toString());
}
}
// If this is an Actual or Encumbrance journal on an 11.0 instance, throw an
exception as
// this is not supported.
else
{
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.getDomainValues()
Exception: Period Name cannot be +
uploaded for Actual and Encumbrance Jnls in
R11.0 ");
throw new BneFatalException
(BneResourceString.getMlsString("UPL_ER_PERIOD_NAME_LOV"));
}
return rs;
}
/**
* Method: validateColumn
*
* <p>This method validates the Period Name on a per-line basis.
*
* @param context - All the valid session information for the current user session.
* @param requestParameters - A hashtable containing the document and upload page
* parameters and their associated values.
* @param columnValues - A hashtable containing all the values for the current upload
row in the spreadsheet.
* @param currentColumn - Information about the column being uploaded. This includes
the
* column name and value.
* @return An empty BneUploaderMessage array is returned when the column is valid, and
a
* BneUploaderMessage array containing relevant upload messages is returned
when
* the column is invalid. Messages can be error, exception or warning
messages.
* Warning messages will not stop the Upload process.
*/
public BneUploaderMessage [] validateColumn(BneWebAppsContext context,
Hashtable requestParameters,
Hashtable columnValues,
BneUploadColumn currentColumn)
{
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.validateColumn() Start");
109
Company Confidential - For internal use only
BneUploadColumn tempBudgetName = null;
BneUploadColumn tempActualFlag = null;
BneUploadColumn tempAccountingDate = null;
boolean accountingDateFlag = false;
Date accountingDate = null;
long setOfBooksId = -1;
long budgetVersionId = -1;
String budgetName = null;
String periodName = null;
String actualFlag = null;
String key = null;
// Get the interface name to allow for retrieval of the column values - i.e.
GL_INTERFACE
String tableName = currentColumn.getInterfaceName();
BneSQLStatement extraSQL = new BneSQLStatement(" PS.PERIOD_NAME LIKE ?");
try
{
// Get all information for the ACTUAL_FLAG upload column.
tempActualFlag =
(BneUploadColumn)columnValues.get(BneStringUtils.concatSeperatorUnlessEmpty(tableName,
"ACTUAL_FLAG",
BneConstants.BNE_DEFAULT_SEPARATOR));
if ( tempActualFlag == null )
{
throw new Exception(BneResourceString.getMlsString("UPL_ER_ACTUAL_FLAG"));
}
// Get the ACTUAL_FLAG column value from the ACTUAL_FLAG upload column
information.
actualFlag = (String)tempActualFlag.getColumnValueAsObject();
if ( tempBudgetName == null)
{
currentColumn.flagColumnAsInvalid();
String msgStr =
BneResourceString.getMlsString("UPL_ER_NO_BUDGET_VERSION");
return (uploadError(currentColumn, msgStr,
"BneOAPeriodNameValidator"));
}
else
{
// Get the BUDGET_VERSION_ID column value from the BUDGET_VERSION_ID
upload column information.
budgetVersionId = Long.parseLong(tempBudgetName.getColumnValue());
}
110
Company Confidential - For internal use only
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.validateColumn key
= " + key);
// Next, get the cached SQL Handle based on the key, however if it does
not exist,
// it must be created and added to the cache.
sqlHandleObject = m_Statements.get(key);
SQLHandle = null;
if (sqlHandleObject != null)
{
SQLHandle = (BneOAPeriodNameSQL)sqlHandleObject;
}
else
{
SQLHandle = new BneOAPeriodNameSQL(context, BUD_JOURNAL_NO_ACCT_DATE,
extraSQL.getStatement());
m_Statements.put(key, SQLHandle);
}
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.validateColumn()
got " + ((Integer)row [0]).intValue());
// If one or more rows are returned from the query, then the column value
is Valid.
if (((Integer)row[0]).intValue() > 0)
{
currentColumn.flagColumnAsFineGrainValid();
return (new BneUploaderMessage[0]);
}
else
{
String msgStr =
BneResourceString.getMlsString("UPL_ER_PERIOD_INVALID");
return (uploadError(currentColumn, msgStr,
"BneOAPeriodNameValidator"));
}
}
else if ((BneTechStack.getMiddleTierAppsRelease() > 11) &&
("A".equals(actualFlag) || "E".equals(actualFlag)))
{
// Period Name is not a mandatory interface column therefore the column is
defined as FineGrainValid when it
// does not contain a value.
if (periodName == null || periodName.equals(""))
{
currentColumn.flagColumnAsFineGrainValid();
return (new BneUploaderMessage[0]);
}
tempAccountingDate =
(BneUploadColumn)columnValues.get(BneStringUtils.concatSeperatorUnlessEmpty( tableName,
"ACCOUNTING_DATE",
BneConstants.BNE_DEFAULT_SEPARATOR));
if (tempAccountingDate == null)
{
throw new Exception
(BneResourceString.getMlsString("UPL_ER_NO_ACCOUNT_DATE"));
}
// Set the accountingDateFlag to false to mark that the SQL result set is
not
111
Company Confidential - For internal use only
// limited by accountingDate - first we want to check that the period is
in an open
// or future-enterable period. The accounting date is not required for
this check.
accountingDateFlag = false;
key = actualFlag + "," +
setOfBooksId + "," +
accountingDateFlag;
sqlHandleObject = m_Statements.get(key);
SQLHandle = null;
if (sqlHandleObject != null)
{
SQLHandle = (BneOAPeriodNameSQL)sqlHandleObject;
}
else
{
// The following query ensures that the Period is an open or future-
enterable period. (This is the
// first business rule that is checked)
if ("A".equals(actualFlag))
{
SQLHandle = new BneOAPeriodNameSQL(context,
ACT_JOURNAL_NO_ACCT_DATE, extraSQL.getStatement());
}
else
{
SQLHandle = new BneOAPeriodNameSQL(context,
ENC_JOURNAL_NO_ACCT_DATE, extraSQL.getStatement());
}
m_Statements.put(key, SQLHandle);
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.validateColumn()
got " + ((Integer)row[0]).intValue());
// Set the accountingDateFlag to true to mark that the SQL result set is
// limited by accountingDate. This tests that the Accounting Date falls
within
// the selected Period.
accountingDateFlag = true;
key = actualFlag + "," +
setOfBooksId + "," +
accountingDateFlag;
sqlHandleObject = m_Statements.get(key);
SQLHandle = null;
112
Company Confidential - For internal use only
// The following query ensures that the Period includes the accounting
date. (This is the second
// business rule that is checked)
if (sqlHandleObject != null)
{
SQLHandle = (BneOAPeriodNameSQL)sqlHandleObject;
}
else
{
if ("A".equals(actualFlag))
{
SQLHandle = new BneOAPeriodNameSQL(context,
ACT_JOURNAL_WITH_ACCT_DATE, extraSQL.getStatement());
}
else
{
SQLHandle = new BneOAPeriodNameSQL(context,
ENC_JOURNAL_WITH_ACCT_DATE, extraSQL.getStatement());
}
m_Statements.put(key, SQLHandle);
}
java.util.Date utilDate =
tempDateFormat.parse(tempAccountingDate.getColumnValue());
accountingDate = new java.sql.Date(utilDate.getTime());
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.validateColumn()
got " + ((Integer)row[0]).intValue());
// If one or more rows are returned from the query, then the column value
is Valid.
// i.e. The Accounting Date falls within the selected Period.
if (((Integer)row[0]).intValue() > 0)
{
currentColumn.flagColumnAsFineGrainValid();
}
else
{
String msgStr = BneResourceString.getMlsString("UPL_ER_PER_NO_ACTDT");
return (uploadError(currentColumn, msgStr,
"BneOAPeriodNameValidator"));
}
}
currentColumn.flagColumnAsFineGrainValid();
return (new BneUploaderMessage[0]);
}
catch (Exception e)
{
/**
* Method: shutdownValidator
*
* <p>This method closes the Period Name validator. Any open cursors are closed in
* this method.
*
* @return Any relevant upload messages. An empty array of BneUploaderMessage is
returned
* when there are no errors.
113
Company Confidential - For internal use only
*/
public BneUploaderMessage [] shutdownValidator ()
{
m_Logger.log(BneTrace.TRACE, "BneOAPeriodNameValidator.shutdownValidator()
Start");
if (m_Statements != null)
{
Enumeration stmts = m_Statements.keys();
while (stmts.hasMoreElements())
{
Object k = stmts.nextElement();
Object o = m_Statements.get(k);
BneOAPeriodNameSQL SQLHandle = (BneOAPeriodNameSQL)o;
SQLHandle.close();
m_Statements.remove(k);
}
m_Statements = null;
}
package oracle.apps.bne.integrator.component.gl;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.util.Hashtable;
import java.util.Vector;
import javax.servlet.http.HttpServletRequest;
import oracle.apps.bne.exception.BneException;
import oracle.apps.bne.exception.BneParameterException;
import oracle.apps.bne.exception.BneSQLException;
import oracle.apps.bne.exception.BneMissingParameterException;
import oracle.apps.bne.framework.BneBajaContext;
import oracle.apps.bne.framework.BneBajaPage;
import oracle.apps.bne.framework.BneConstants;
import oracle.apps.bne.framework.BneWebAppsContext;
import oracle.apps.bne.integrator.component.BneAbstractListOfValues;
import oracle.apps.bne.integrator.validators.gl.BneOAPeriodNameValidator;
import oracle.apps.bne.parameter.BneParameter;
import oracle.apps.bne.parameter.BneParameterList;
import oracle.apps.bne.repository.BneResourceString;
import oracle.apps.bne.utilities.sql.BneCompositeSQLCriteria;
import oracle.apps.bne.utilities.sql.BneResultSet;
import oracle.apps.bne.utilities.sql.BneSimpleSQLCriteria;
import oracle.apps.bne.webui.control.BneLOVControlBean;
114
Company Confidential - For internal use only
import oracle.apps.fnd.common.VersionInfo;
import oracle.cabo.servlet.Page;
import oracle.cabo.servlet.event.PageEvent;
import oracle.cabo.ui.data.DictionaryData;
/**
* Class BneOAPeriodNameComponent
*
*
* @author John Smith
* @version $Revision: $ $Date: $
*/
public class BneOAPeriodNameComponent extends BneAbstractListOfValues
{
/**
* RCS version insertion into <code>VersionInfo</code> on class loading.
*/
public static final boolean RCS_ID_RECORDED = VersionInfo.recordClassVersion(RCS_ID,
"oracle.apps.bne.integrator.component.gl");
/**
* Private variables
*/
private BneWebAppsContext m_bneWebAppsContext = null;
private BneOAPeriodNameValidator m_validator = null;
private String[] m_validatorParameters = null;
//
// Basic Filter Search Values
//
private String m_filterField = null;
private String m_filterValue = null;
/**
* Method: getLOVProcessorType
* <p>
* The viewer processes the Period Name LOV as a TABLE.
*
* @return the viewer processor type TABLE.
*/
public String getLOVProcessorType()
{
return BneConstants.BNE_LOV_TYPE_TABLE;
}
/**
* Method: init
* <p>
* This method instantiates the BneOAPeriodNameValidator class and calls
getDomainParameters
* to create a String array of the interface column names required by the Component.
*
* @param context The interface providing context about the current http request,
and
* providing access to generic Baja Services.
* @param page Identifies the Period Name LOV page.
* @param event The interface for events triggered on the Period Name LOV page.
Encapsulates
* a servlet request.
*
*/
public void init (BneBajaContext context,
Page page,
PageEvent event)
{
if (m_validator == null)
{
m_validator = new BneOAPeriodNameValidator();
115
Company Confidential - For internal use only
m_validatorParameters = m_validator.getDomainParameters();
}
}
/**
* Method: handleListOfValues
* <p>
* This method returns a BneBajaPage containing display information for the Period
Name LOV page.
*
* @param context The interface providing context about the current http request,
and
* providing access to generic Baja Services.
* @param page Identifies the Period Name LOV page.
* @param event The interface for events triggered on the Period Name LOV page.
Encapsulates
* a servlet request.
* @param bean Holds information about the Period Name LOV.
*
* @return a BneBajaPage
*
* @throws BneException
*
*/
public BneBajaPage handleListOfValues (BneBajaContext context,
Page page,
PageEvent event,
BneLOVControlBean bean) throws BneException
{
BneWebAppsContext ctx = context.getBneWebAppsContext();
BneCompositeSQLCriteria searchCriteria = null;
Hashtable parameterValues = new Hashtable();
String tableHeaderString =
BneResourceString.getMlsString("LOV_PERIOD_NAME");
String[] tableHeaders = {tableHeaderString};
String[] tableColumns = {"PERIOD_NAME"};
String[] tableSelectColumn = {"PERIOD_NAME"};
BneSimpleSQLCriteria.TYPE_NONE,
BneSimpleSQLCriteria.LIKE, m_filterValue,
BneSimpleSQLCriteria.TYPE_STRING);
simpleCriteria.setSearchsCaseInsensitivity(true);
searchCriteria.addCriteria(simpleCriteria);
}
setTableFilter(true);
setPageTitle(getParameterValue(context.getBneWebAppsContext(), "window-caption"));
setTableData(getTableData(ctx, bean, parameterValues, searchCriteria));
setTableColumns(tableColumns);
setTableHeaders(tableHeaders);
setTableSelectColumn(tableSelectColumn);
return null;
}
/**
* Method: getListOfValueParameters
* <p>
116
Company Confidential - For internal use only
* This method creates a BneParameterList object consisting of one record for each
parameter in the
* m_validatorParameters String array (created in the init method).
*
* @throws BneParameterException
*/
public void getListOfValueParameters () throws BneParameterException
{
/**
* Method: handlePageParameters
* <p>
* This method does an http get to retrieve the values entered in the filter fields in
the Period Name LOV page.
*
* @param context The interface providing context about the current http request,
and
* providing access to generic Baja Services.
* @param page Identifies the Period Name LOV page.
* @param event The interface for events triggered on the Period Name LOV page.
Encapsulates
* a servlet request.
*
* @throws BneException
*/
private void handlePageParameters (BneBajaContext context,
Page page,
PageEvent event) throws BneException
{
HttpServletRequest httpRequest = context.getServletRequest();
m_filterField = httpRequest.getParameter("listOfValues:bne:filterField");
m_filterValue = httpRequest.getParameter("listOfValues:bne:filterValue");
}
/**
* Method: getTableData
*
*
* @param bneWebAppsContext All the valid session information for the current user
session.
* @param bean Holds information about the Period Name LOV control
* @param parameterValues This is a hashtable containing the list of all columns and
their
* values that are required by the SQL that will derive the
list of values.
* @param criteria This contains all the details for the Period Name LOV Component.
*
* @return a DictionaryData object containing all the Period values that will be
displayed on the LOV page.
*
* @throws BneException
*
*/
public DictionaryData [] getTableData (BneWebAppsContext bneWebAppsContext,
BneLOVControlBean bean,
Hashtable parameterValues,
BneCompositeSQLCriteria criteria) throws
BneException
{
DictionaryData sqlRow = null;
Vector myRows = new Vector();
BneResultSet rs = null;
ResultSetMetaData rsmd = null;
try
{
String columnValue = null;
117
Company Confidential - For internal use only
rs = m_validator.getDomainValues(bneWebAppsContext, parameterValues,
criteria);
if (rs != null)
{
rsmd = rs.getResultSet().getMetaData();
while (rs.next())
{
sqlRow = new DictionaryData();
if (columnValue == null)
{
sqlRow.put(rsmd.getColumnName(i), "");
}
else
{
sqlRow.put(rsmd.getColumnName(i), columnValue);
}
}
myRows.addElement(sqlRow);
}
}
}
catch (SQLException e)
{
throw new
BneSQLException(BneResourceString.getMlsString("UPL_PERIOD_NAME_SQL_EXCEPTION"), e);
}
catch (BneMissingParameterException mpe)
{
bean.addError(mpe.getMessage());
}
finally
{
m_validator.shutdownValidator();
}
return allData;
}
/**
* Method: getComponentName
*
* @return a String containing the name of the Component.
*
*/
public String getComponentName ()
{
return "BneOAPeriodName";
}
/**
* Method: getComponentVersion
*
* @return a String containing the revision identifier for the Component.
*
*/
public String getComponentVersion ()
{
return "$Revision: $";
118
Company Confidential - For internal use only
}
}
119
Company Confidential - For internal use only
Sample Metadata for the Period Name Java Validation
1.1.1.13 BNE Parameter Definition Sample Metadata for the Period Name Validator/LOV
The following three parameter definitions are defined for the Period Name example.
1.1.1.14 BNE_PARAM_DEFNS_B
APPLICATION_ID 231
PARAM_DEFN_CODE OA_PER_NAME_WIN_CAP
OBJECT_VERSION_NUMBER 1
PARAM_NAME Web ADI Components: OA_PERIOD_NAME window-caption
PARAM_SOURCE WEBADI:Components
PARAM_CATEGORY 3
DATATYPE 1
DEFAULT_REQUIRED_FLAG N
DEFAULT_VISIBLE_FLAG Y
DEFAULT_USER_MODIFYABLE_FLAG Y
VAL_TYPE 1
MAX_SIZE 100
DISPLAY_TYPE 4
DISPLAY_STYLE 1
DISPLAY_SIZE 100
APPLICATION_ID 231
PARAM_DEFN_CODE TABLE_BLOCK_SIZE
OBJECT_VERSION_NUMBER 1
PARAM_NAME table-block-size
PARAM_SOURCE WEBADI:Components
PARAM_CATEGORY 5
DATATYPE 2
DEFAULT_REQUIRED_FLAG N
DEFAULT_VISIBLE_FLAG Y
DEFAULT_USER_MODIFYABLE_FLAG Y
DEFAULT_NUMBER 25
VAL_TYPE 1
MAX_SIZE 100
DISPLAY_TYPE 4
DISPLAY_STYLE 1
DISPLAY_SIZE 10
120
Column Name Column Value
APPLICATION_ID 231
PARAM_DEFN_CODE TABLE_SELECT_COLUMN
OBJECT_VERSION_NUMBER 1
PARAM_NAME table-select-column
PARAM_SOURCE WEBADI:Components
PARAM_CATEGORY 5
DATATYPE 1
DEFAULT_REQUIRED_FLAG N
DEFAULT_VISIBLE_FLAG Y
DEFAULT_USER_MODIFYABLE_FLAG Y
VAL_TYPE 1
MAX_SIZE 100
DISPLAY_TYPE 4
DISPLAY_STYLE 1
DISPLAY_SIZE 20
BNE_PARAM_DEFNS_TL
APPLICATION_ID 231
PARAM_DEFN_CODE OA_PER_NAME_WIN_CAP
LANGUAGE US
SOURCE_LANG US
USER_NAME Title to place on window caption bar.
DEFAULT_STRING Search and Select Period Name
DEFAULT_DESC Search and Select Period Name
PROMPT_LEFT window-caption
PROMPT_ABOVE window-caption
USER_TIP Title to place on window caption bar.
APPLICATION_ID 231
PARAM_DEFN_CODE TABLE_BLOCK_SIZE
LANGUAGE US
SOURCE_LANG US
USER_NAME Determines if the number of records to display.
DEFAULT_DESC Number of records to show in an lov
PROMPT_LEFT table-block-size
PROMPT_ABOVE table-block-size
USER_TIP Determines if the number of records to display.
APPLICATION_ID 231
PARAM_DEFN_CODE TABLE_SELECT_COLUMN
121
Company Confidential - For internal use only
Column Name Column Value
LANGUAGE US
SOURCE_LANG US
USER_NAME Select column, comma-seperated list of columns to be selected. If aliases exist
then use the alias name. Example: NAME,DEPT
PROMPT_LEFT table-select-column
PROMPT_ABOVE table-select-column
USER_TIP Select column, comma-seperated list of columns to be selected. If aliases exist
then use the alias name. Example: NAME,DEPT
122
Company Confidential - For internal use only
BNE Parameter List Sample Metadata for the Period Name Validator/LOV
The following parameter list is defined for the Period Name example.
BNE_PARAM_LISTS_B
APPLICATION_ID 231
PARAM_LIST_CODE COMP_PERIOD_NAME
OBJECT_VERSION_NUMBER 1
PERSISTENT_FLAG Y
COMMENTS This list is used for the OA_PERIOD_NAME Component.
BNE_PARAM_LISTS_TL
APPLICATION_ID 231
PARAM_LIST_CODE COMP_PERIOD_NAME
LANGUAGE US
SOURCE_LANG US
USER_NAME Web ADI: OA_PERIOD_NAME Component
BNE Parameter List Items Sample Metadata for the Period Name Validator/LOV
BNE_PARAM_LIST_ITEMS
APPLICATION_ID 231
PARAM_LIST_CODE COMP_PERIOD_NAME
123
Company Confidential - For internal use only
Column Name Column Value
SEQUENCE_NUM 1
PARAM_DEFN_APP_ID 231
PARAM_DEFN_CODE TABLE_SELECT_COLUMN
STRING_VALUE PERIOD_NAME
DESC_VALUE PERIOD_NAME
APPLICATION_ID 231
PARAM_LIST_CODE COMP_PERIOD_NAME
SEQUENCE_NUM 2
PARAM_DEFN_APP_ID 231
PARAM_DEFN_CODE OA_PER_NAME_WIN_CAP
PARAM_NAME window-caption
APPLICATION_ID 231
PARAM_LIST_CODE COMP_PERIOD_NAME
SEQUENCE_NUM 3
PARAM_DEFN_APP_ID 231
PARAM_DEFN_CODE TABLE_BLOCK_SIZE
STRING_VALUE 25
DESC_VALUE 25
BNE_COMPONENTS_B
APPLICATION_ID 231
COMPONENT_CODE OA_PERIOD_NAME
OBJECT_VERSION_NUMBER 1
COMPONENT_JAVA_CLASS oracle.apps.bne.integrator.component.gl.BneOAPeriodNameComponent
PARAM_LIST_APP_ID 231
PARAM_LIST_CODE COMP_PERIOD_NAME
BNE_COMPONENTS_TL Table
APPLICATION_ID 231
124
Company Confidential - For internal use only
Column Name Description
COMPONENT_CODE OA_PERIOD_NAME
LANGUAGE US
SOURCE_LANG US
USER_NAME OA_PERIOD_NAME Component
BNE Interface Column(s) Sample Metadata for the Period Name Validator/LOV
BNE_INTERFACE_COLS_B Table
APPLICATION_ID 231
INTERFACE_CODE GL_INTERFACE_115
OBJECT_VERSION_NUMBER 1
SEQUENCE_NUM 83
VAL_TYPE JAVA
VAL_OBJ_NAME oracle.apps.bne.integrator.validators.gl.BneOAPeriodNameValidator
VAL_COMPONENT_APP_ID 231
VAL_COMPONENT_CODE OA_PERIOD_NAME
LOV_TYPE STANDARD
OFFLINE_LOV_ENABLED_FLAG N
125
Company Confidential - For internal use only
Column Name Column Value
APPLICATION_ID 231
INTERFACE_CODE GL_INTERFACE_115
SEQUENCE_NUM 138
INTERFACE_COL_TYPE 2
INTERFACE_COL_NAME REVERSAL_PARENT
ENABLED_FLAG Y
REQUIRED_FLAG N
DISPLAY_FLAG N
READ_ONLY_FLAG N
NOT_NULL_FLAG N
SUMMARY_FLAG N
MAPPING_ENABLED_FLAG N
GROUP_NAME REVERSAL
VAL_TYPE GROUP
VAL_OBJ_NAME oracle.apps.bne.integrator.validators.gl.BneOAReversalGroupValidator
LOV_TYPE NONE
OFFLINE_LOV_ENABLED_FLAG N
APPLICATION_ID 231
INTERFACE_CODE GL_INTERFACE_115
SEQUENCE_NUM 58
INTERFACE_COL_NAME REFERENCE7
GROUP_NAME REVERSAL
APPLICATION_ID 231
INTERFACE_CODE GL_INTERFACE_115
SEQUENCE_NUM 59
INTERFACE_COL_NAME REFERENCE8
GROUP_NAME REVERSAL
126
Company Confidential - For internal use only
APPENDIX D Security
Web ADI provides a level of function security within its framework that allows
declarative rules to be applied to an integrator to lock out users who should not be
able to access an Integrator. This level of security is mandatory in Web ADI (refer
section 2.2 Associate Form Function(s) with Integrator).
This function security does not prevent the writer of the Integrator introducing
security holes that allow valid users to perform illegal actions. This is something the
Integrator Developer must be aware of as they develop their solution, in a similar
manner as they would when writing OA pages.
Spreadsheets may exist for a long time. They may be saved, copied, emailed
and re-used a number of times.
Spreadsheets can be reused by a different user than the one that created it.
The conditions/data that the spreadsheet was created under may have
changed.
When a Web ADI spreadsheet is generated, information is placed in the code of the
sheet that allows that spreadsheet to interact with the middle tier using business
rules defined for the Integrator. Placing this information in the spreadsheet allows
the sheet to be reused over large periods of time.
Content Parameters,
Upload Parameters,
LOV Parameters.
Some of these parameter values may be particular to the user that created the sheet,
and to the user selections made when creating the sheet; this is up to the Integrator
Developer when creating the Integrator. Web ADI does not understand what these
parameters mean, they are specific to the problem domain of the Integrator
Developer.
These parameter values can be tampered in the spreadsheet by a user, and the
tampered value will be sent to the middle tier. Any parameter whose value is used
for configuration must be checked for validity before use by code running in the
middle tier.
The previous discussion on parameters does not include the spreadsheet user data
itself, which may also need to be checked. For example, Spreadsheet values that
allow configuration such as the ledger must be re-checked to ensure the entered
value is valid for the user.
127
Examples - Download
For example, a stored SQL download may have a parameter that is the userid of a
user to download data for. This userid is supposed to be the user running the
Integrator solution. If this userid is declared as a content parameter it will be stored
in the spreadsheet and passed to the download service when the download is
performed (either at sheet creation or on any number of subsequent downloads
even months later when run as a different user).
Scenario 1: Sheet is cleared of data and emailed to another user (user 2).
Scenario 2: User modifies the sheet and changes the user id.
Both of these scenarios are the result of trusting data/parameters coming from the
client. In this example they can be simply fixed by using a token in the SQL query
$env$.userid which will be bound with the logged in users userid whoever that
user may be when they run the sheet. This is an example of using secure middle tier
information protected by the login process.
Another solution, and one more applicable for complex parameter situations is to re-
check the parameters when sent to the sheet i.e. always be suspicious of everything
sent from the client. The following decorator may be used as an example of how
this may be done for a stored SQL control.
import java.sql.Connection;
import java.util.Enumeration;
import java.util.Hashtable;
import oracle.apps.bne.exception.BneException;
import oracle.apps.bne.exception.BneParameterException;
import oracle.apps.bne.framework.BneKey;
import oracle.apps.bne.framework.BneTrace;
import oracle.apps.bne.framework.BneWebAppsContext;
import oracle.apps.bne.repository.BneMapObject;
import oracle.apps.bne.webui.control.BneStoredSQLControl;
import oracle.apps.fnd.common.VersionInfo;
import oracle.apps.fnd.common.WebAppsContext;
/**
* This class is presented as an example of how project teams may do additional validation
128
Company Confidential - For internal use only
* for their stored SQL contents, where the query cannot contain the logic necessary (i.e it's
* too hard to put into a single SQL query).<p>
*
* Project teams need to create their own copy of this class under their own java directories
* ($psa/java) and ship it in their patch. DO NOT ship it under the Web ADI (bne) area,
* product teams will need to change the package as appropriate.<p>
*
* Project teams will also need to change the BNE_CONTENTS_B.CONTENT_CLASS column for their content
* to point to this class. For example, replace <br>
* 'oracle.apps.bne.webui.control.BneStoredSQLControl'<br>
* with <br>
* 'oracle.apps.XXX.webui.control.BneExampleStoredSQLControl'<p>
* If this contnet has already been shipped, remember to update the LAST_UPDATE_DATE on this
* SEED data row so FNDLOAD will upload it.
*
* @author David Groves david.groves@oracle.com
U U
* @version $Revision$
*/
/**
* Open the datasource for reading. This method is called before any data is read with next().
*
* @param context see BneWebAppsContext definition.
* @param mapDefinition the map object for the selected mapping template.
* It can be used to obtain data such as column separator.
* @param controlParameters name/value pairs (Strings) of the parameters to use to do the download. These
* have been sent form the viewer via HTTP and have not been converted into their correct datatypes or
* decoded into BneParameters for simplicity.
* @param environmentParameters environmental parameters. Initially there are two parameters that the
* control should conform to:<ol><li>
* NLS_NUMERIC_CHARACTERS - the characters that act as decimal and thousand separators. Eg. ".,"</li><li>
* NLS_DATE_FORMAT - the date format to return dates in. Note that this is a Java SimpleDateFormat format
* mask, similar but different to the standard Oracle data format mask. Eg. "yyyy-MM-dd"</li></ol>
* @param contentId key to content.
* @param layoutId key to layout. This is used by some implementations to restrict the columns sent to the
* client.
* @throws BneException
* @see BneDownloadDataInterface
*/
public void open (BneWebAppsContext context,
BneMapObject mapDefinition,
Hashtable controlParameters,
Hashtable environmentParameters,
BneKey contentId,
BneKey layoutId)
throws BneException
{
// Connection and wac that may be useful for obtaining data/running queries.
Connection con = context.getJDBCConnection();
WebAppsContext wac = context.getWebAppsContext();
129
Company Confidential - For internal use only
// At this point, all parameters are determined to be valid. Do the "default" action.
super.open(context, mapDefinition, controlParameters, environmentParameters, contentId, layoutId);
}
}
When uploading, the chart of accounts sent with the upload data needs to be tested against the chart of accounts
currently assigned to the user. If they are not the same, an error needs to be generated and the upload halted.
When performing LOVs, the chart of accounts may be sent to the LOV and the LOV data filtered by this value.
The Chart of Accounts value needs to be validated before use in the LOV, and if invalid an error should be
generated.
Security Contexts
130
Company Confidential - For internal use only
For some applications, these concepts will be handled with a security context defined for that application
(virtual private database), in which case little or no code will be required as data that is not relevant to the user
will not be available. Caution should be used to ensure all data falls into this security context.
Input Filter
All data sent to the Web ADI middle tier is scanned for input filter violations. This includes HTTP parameters
and all upload data points (every cell in the spreadsheet).
The input filter checks will not catch bad data values however, this needs to be done by the Integrator Developer.
131
Company Confidential - For internal use only