39001601 Web ADI Integrator Developer’s Guide

USER GUIDE

Oracle Corporation

Web ADI Integrator Developers Guide

Author: Alex Drexel

Creation Date: April 18, 2002

Last Updated: May 3rd, 2005

Document Ref: 01

Version: 2.0

Approvals:

John Richardson

Brett Hooker

Copy Number _____

Document Control

Change Record 5

Date Author Version Change Reference

18-Apr-02 Alex Drexel 1 No Previous Document 24-Jun-02 Alex Drexel 1.1 Changes to include more info on Parameter UI and

PL/SQL 23-Aug-02 Alex Drexel 1.2 Added Expanded Cols and general edits. 19-Sept-02 Alex Drexel 1.3 Added Reporting Mode 4-Nov-02 Bernardine Rodgers 1.4 Updated API Definitions for 8.3 8-Nov-02 Alex Drexel 1.5 Removed References to Directory and other tables,

columns, and parameters not present in 8.3. Updated Calling Web ADI.

10-Mar-04 Alex Drexel 1.6 Instructed Integrator developers to create their own parameter definitions for upload parameters in section 7.2.1. Noted the parameters in LOV parameter lists that are optional in section 5.1.2.

23-Sep-04 Alex Drexel 1.7 Updates per bug 3901271. Added additional information regarding Java validators and Function security.

09-Mar-05 Alex Drexel 1.8 Added more detail to section Uploading Code Combination Identifier For Key Flexfield Values

17-Mar-05 Alex Drexel 1.9 Updated section added in v1.8. 03-May-05 Alex Drexel 2.0 Updated the val obj class to use when defining key

flexfields.

Contributors

Name Position Contribution

Katherine Peet Product Analyst Definitions in Glossary

Document Reference

Author Document Name

David Groves Web ADI Parameters DLD Component Parameters DLD Web ADI PA Download_DLD_CreateDoc Web ADI Download Metadata DLD TokenRedirectNoReview Paul Cross Insert to API and Multi-Table Upload DLD Metadata Importer DLD Gordon Hooker Web ADI Download Stored SQL DLD Mapping Template Page Flow DLD Kathryn Dobinson Metadata Driven Upload Parameters DLD Web ADI Download Passed SQL DLD Alex Drexel Integrator Developers Guide

Company Confidential - For internal use only

ii

Reviewers

Name Position

John Richardson Group Manager

Distribution

Copy No. Name Location

1 Library Master Project Library Files On line 2 3 4


iii

Contents

Document Control ..................................................................................................................ii

Glossary....................................................................................................................................6

1. Overview ...................................................................................................................9 1.1. Functionality ......................................................................................................9 1.2. Integrator Development ...................................................................................9

2. Defining an Integrator ...........................................................................................11 2.2 Associate Form Function(s) with Integrator ........................................................11 To Delete an Association ..............................................................................................12 To Update an Association ............................................................................................12

3. Adding Interfaces ...................................................................................................14 3.1. Creating a PL/SQL API Interface .................................................................14 3.2. Creating a Table Interface ..............................................................................18 3.3. Uploading to Multiple Interface Tables or APIs .........................................19

4. Updating Interface Columns/API Parameters ..................................................20 4.1. Create Interface Columns...............................................................................20 4.2. Interface Columns Concepts..........................................................................22

5. Creating Components ............................................................................................32 5.1. Creating Table Validated Components ........................................................32 5.2. Creating JAVA Validated Components .......................................................35 SQL Java Class ...............................................................................................................37 Validator Java Class ......................................................................................................40 Implementing a Group Validator Java Class.............................................................44 Component Java Class ..................................................................................................46 Implementing the Component Java Class..................................................................47

Metadata for Java Validation ..............................................................................................51 BNE Parameter Definition Tables ...............................................................................51 BNE Parameter List Tables...........................................................................................52 BNE Parameter List Items Table..................................................................................53 BNE Component Tables................................................................................................53 BNE Interface Column(s) Tables .................................................................................54

6. Defining an Importer .............................................................................................57 6.1. Indicate Importer Type...................................................................................57 6.2. Define Master Parameter List ........................................................................58 6.3. Enter Metadata for Steps in Master List.......................................................60


iv

7. Defining Upload Parameters ................................................................................79 7.1. Upload Parameters Screen .............................................................................79 7.2. Create Upload Parameter List .......................................................................80

8. Creating Content ....................................................................................................82 8.1. Stored SQL........................................................................................................82 8.2. Text File.............................................................................................................84 8.3. Java ....................................................................................................................86

9. Reporting Only Documents ..................................................................................88 9.1. Reporting only with Data Entry Interfaces..................................................88 9.2. Reporting only Interfaces, Mappings and Layouts ....................................88

10. Creating Layouts and Mappings..........................................................................90 10.1. Creating Layouts .............................................................................................90 10.2. Creating Mappings .........................................................................................94

11. Calling the Create Doc Page Flow........................................................................97 11.1. Available Parameters......................................................................................97 11.2. Sending Parameters to BneApplicaitonService...........................................99

APPENDIX A Parameter UI...........................................................................................103 Accessing Parameter UI..............................................................................................103 Defining Parameter Lists ............................................................................................103 Defining Parameter List Items ...................................................................................103 Defining a Parameter Definition ...............................................................................104 Associating a Parameter Definition to a Parameter................................................104 Testing Your Parameter List ......................................................................................104

APPENDIX B Shipping Your Integrator.......................................................................106

1.2 Appendix C ...........................................................................................................108

Open and Closed Issues for this Deliverable ......................................................................6 Open Issues.......................................................................................................................6 Closed Issues ....................................................................................................................6


v

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.

Create Document Page Flow

This page flow consists of a set of Web ADI screens from which an end user can select from several parameters to create a document on the client machine. The parameters that a user can select include: Language, Viewer, Integrator, Layout, Content and Mapping. Additional parameters may be required depending on the Content selected.

Document Creation Shortcut Settings

These settings are the parameters that are supplied to the Create Document page flow. These parameters are passed to the Create Document page flow either when a user selects a Document Creation Shortcut from the Documents page in the Create Document page flow or when the Create Document page flow is called directly from an application or form. (Aside: the Documents page the first page in the Create Document page flow but will not be displayed until a Shortcut has been saved.)

Dynamic Parameter

A dynamic parameter is a parameter defined by metadata stored in the Web ADI repository, but its value must be determined at run-time.

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.


7

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.


8

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.

By updating metadata, Integrator Developers can have Web ADI:

Create a formatted document on the desktop containing application specific fields for data entry. Import data from the database or a text file to a document. Provide List of Values within a document. Upload data from the desktop document to Oracle Applications. 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.

1.2. Integrator Development

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.

Developing an Integrator involves the following steps:

Define an Integrator Define Interfaces Define Interface Columns Create Components Define Importer


9

Defining Upload Parameters Defining Upload Parameters Creating Content(s) Creating Content(s) Creating Layouts and Mappings Creating Layouts and Mappings This document describes these steps in detail and provides information on how Web ADI can be invoked. This document describes these steps in detail and provides information on how Web ADI can be invoked.

Note: The Apache HTTP listener must be restarted when a record is updated through SQL Plus if the change is to be viewed in the application.

10 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.

2.1 Create Integrator

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 - . 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.

2.2 Associate Form Function(s) with Integrator You must associate at least one form function with your integrator. Web ADI will check to see if a users current responsibility has access to any one of the associated form functions before a document is created, an upload is conducted, or an LOV is rendered. Associated form functions will also be checked before a user can define a layout or a mapping for an Integrator. Do not use the Create Document form function; it should be a form function your team ships.

Call the following Package: 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);



11


P_APPLICATION_ID Application ID of your product

P_OBJECT_CODE Enter the code of the Integrator you want to apply the security rule to.

P_OBJECT_TYPE Pass INTEGRATOR P_SECURITY_CODE Security Code uniquely

identifies the security rule. P_SECURITY_TYPE Enter FUNCTION P_SECURITY_VALUE A comma separated list of

functions that grant access to your integrator. These form functions must exist on your instance or an error will be received when calling the package.

P_USER_ID Updates CREATED_BY and LAST_UPDATED_BY Columns. The value for this parameter should be the seed user. When extracted to an LDT file, this value should translate to the Oracle user.

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

P_OBJECT_APP_ID Application ID of your product

P_OBJECT_CODE Enter the code of the Integrator that has the security rule you you want to delete.

P_OBJECT_TYPE Pass INTEGRATOR P_SECURITY_APP_ID Application ID of your

product P_SECURITY_CODE Pass the security rule you

want to delete.

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,


12

P_SECURITY_CODE in VARCHAR2, P_SECURITY_TYPE in VARCHAR2, P_SECURITY_VALUE in VARCHAR2, P_USER_ID in NUMBER);


P_OBJECT_APP_ID Application ID of your product

P_OBJECT_CODE Enter the code of the Integrator you want to apply the security rule to.

P_OBJECT_TYPE Pass INTEGRATOR P_SECURITY_APP_ID Application ID of your

product P_SECURITY_CODE Security Code uniquely

identifies the security rule. P_SECURITY_TYPE Enter FUNCTION P_SECURITY_VALUE A comma separated list of

functions that grant access to your integrator. These forrm funcitons must exist on your instance or an error will be received when calling the package..

P_USER_ID Updates CREATED_BY and LAST_UPDATED_BY Columns. The value for this parameter should be the seed user. When extracted to an LDT file, this value should translate to the Oracle user.


13

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.

3.1. Creating a PL/SQL API Interface

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);



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.

P_API_PROCEDURE_NAME The procedure name of your PL/SQL API. P_INTERFACE_USER_NAME The user name for the Interface, but is not seen in the UI at

this time


14


P_PARAM_LIST_NAME Your Interface to an API will require an associated list of parameters. Set to be the name of this parameter list. This value will not be seen by users.

Set P_API_TYPE PROCEDURE or FUNCTION P_API_RETURN_TYPE The Function Return Data Type. P_UPLOAD_TYPE Set to 0, 1 or 2. 0 = Custom Upload Type (uses

BNE_INTERFACES_B.UPLOAD_OBJ_NAME to obtain class name to load). 1= upload to Table. 2 = Upload to PL/SQL API

P_LANGUAGE The language your Interface name will be stored against P_SOURCE_LANGUAGE The language the Interface name will be translated from Set P_USER_ID ID to a valid Oracle Applications user ID

3.1.2. Identify Attributes of the PL/SQL API

3.1.2.1. Look up the PARAM_LIST_CODE created in the previous step in the Parameter UI (See Appendix A for more information on Parameter UI).

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.

Field Name Field Description

ATTRIBUTE1 Type of API call. (FUNCTION or PROCEDURE.) ATTRIBUTE2 Name of PL/SQL function or procedure including the

package name. ATTRIBUTE3 Function Return Data Type. This attribute will be

ignored if the API is a PROCEDURE ATTRIBUTE4 Whether the return value is used to retrieve the error

messages (Y/N). This attribute will be ignored if the API is a PROCEDURE.

ATTRIBUTE5 Perform a call to FND_MESSAGES. (Y/N). This attribute is used for a FUNCTION and PROCEDURE

Example :


15

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 een. Use this screen to enter the details for each parameter you add the list.

Scr

Field Name Field Description

NAME Name of parameter. This value needs to be the exact name of the parameter in your API. This value is not translatable.

Data Type This is the data Type for the default value for this parameter.

Value Default value for the parameter if known. Description Description of parameter. E.g. Journals for

Applications 11i. This is in the language of the user. Note, a description must be entered if a default value is defined.

Formula An environment variable or similar that the default value can be derived from. E.g. $env$.userid 1318 as a number if DATATYPE=NUMBER


16

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.

Field Name Filed Description

ATTRIBUTE1 PL/SQL parameter name ATTRIBUTE2 PL/SQL parameter data type. ATTRIBUTE3 PL/SQL parameter access. (IN / OUT / INOUT) ATTRIBUTE4 Used for returning error messages. (Y/N) ATTRIBUTE5 Default value for the PL/SQL parameter. You

must use single quotes around any string that is to be used as a default value (i.e. FULL)

ATTRIBUTE6 Size of the variable.

Example:


17

3 in eter 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

3.2. CYou can upload amounts to a table from a desktop document such as Excel. Fields in the document

n the document is uploaded.

3.2

BNE_INTE

P_OBJECT_CODE 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);

.1.4. Create records BNE_INTERFACE_COLS_B for every PL/SQL API param

Columns/API Parameters for more information on creating records in this table.

reating a Table Interface

will represent columns in a table that will be updated whe

.1. Run the following PL/SQL API to create a Table Interface:

GRATOR_UTILS. CREATE_INTERFACE_FOR_TABLE (P_APPLICATION_ID IN NUMBER,

IN VARCHAR2,



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.

P_INTERFACE_TABLE_NAME the name of the table you will be updating P_INTERFACE_USER_NAME is the user name for your interface. Currently, this is not seen by users.


18

every column in your table. Not the

T ore than one Interface table or API, you simply define more than one ill

erface is updated when users upload their documents. This will be useful when uploading

3.2.2. Create records in BNE_INTERFACE_COLS_B for 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.

3.3. Uploading to Multiple Interface Tables or APIs

o define layouts that upload to mInterface for an Integrator. The list of fields a user has to choose from when defining their layouts wcontain 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 Intto APIs since APIs must often be called in a particular order.


19

4. Updating Interface Columns/API Parameters

The columns/para data described in this section te and list of values.

must be en nterface. This ion is stored o enter identify

C ace column metadata.

meters of the Interface tables/APIs must be identified in metadata. The metafacilita s the core Web ADI services including upload, validation, defining Layouts, defining Mappings,

4.1. Create Interface Columns

Metadata tered for evey API Parameter or table column that exists in your I in BNE_ITNERFACE_COLS_B (TL). informat

your columns. Follow the instructions below t

4.1.1. An Interface olumns Integrator is available for you to quickly create/edit interf

4.1.1.1. Y e following script if you do not see a Web ADI Interface Columns Integrator

4.1.1.2. T Create Document Page flow and select layout. The APIs you

ou must run th on the Integrator page of the Create Document Page flow.

update bne_integrators_b

set enabled_flag = 'Y'

where application_id = 231

and integrator_code = 'INTERFACE_COLS';

o quickly create interface columns using Excel, enter theWeb ADI Interface Columns Integrator and the All Columns


20

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

ntent an 3. Records will be downloaded into Excel, where they can be changed/created and uploaded.

a lis s. * = Required

Co d enter the Interface Code you created in the previous section

4.1.2. Below is t of fields that will appear in the spreadsheet and their description

Column (Field) Name Description

APPLICATION_ID The identifier for the application. INTERFACE_CODE* . Select INTERFACE_CODE, INTERFACE_NAME Object Code of the Interface

from BNE_INTERFACES_B to get this value. SEQUENCE_NUM Unique ID for every record that is assigned to the same INTERFACE_CODE. So

you could have the same SEQUENCE_NUM for two records in this table, but they would have to be assigned to different INTERFACE_CODEs.

INTERFACE_COL_TYPE* (Type) the column is an alias that can exist in the layout but is not an actual

1 indicates that this column/parameter exists in the interface table/API. 2 indicates thatcolumn in the interface table.

INTERFACE_COL_NAME* be updated. Interface (Name)

Name of the interface table column or API Parameter totable columns MUST BE ENTERED IN UPPERCASE.

ENABLED* Y/N field indicating if this interface column/API parameter will be updated or included in a Web ADI Layout.

UPLOAD_PARAM_LIST_ITEM_NUM

Identifier of parameters for a PL/SQL API upload. Match this value with the value of SEQ_NUM in BNE_PARAMETER_LIST_ITEMS to identify the parameter being uploaded to.

REQUIRED_FLAG (Required) Y/N field. A Y value will force this column/parameter to be included in all layouts for an Integrator. Users will be required to enter a value for this

he Y.

n when defining new

column/parameter in the document. Columns that cannot be set to NULL in tdatabase and parameter values that are required should have this field set to A N value will allow a User to optionally select this columlayouts for an Integrator. All columns/parameters with the ENABLED field set to N should have a NULL value in this column.

DISPLAY_FLAG (Display) n/parameter will be displayed in in

e user. This configuration can be ve all sheets pass a hidden default

Y/N field determines whether or not the columthe layout. If NO, the user will not be able to select this column to be included the layout. If NO and REQUIRED_FLAG = YES, then the column/parameter will be included in the sheet but wont be seen by th

haused with the DEFAULT_VALUE column tovalue.

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 LUE. Valid values for this field are uses

ENVIRONMENT Indicates an environmental variable defined in DEFAULT_VALUE . SQL indicates a SQL statement exists in DEFAULT_VALUE

ermine the value to be used for this field during upload. efault the value from another column. Default values are

not automatically inserted into the document when it is created, they are derived at upload time.

Indicates the form of the DEFAULT_VASQL, ENVIRONMENT, CONSTANT, and TABLELOOKUP. CONSTANT the actual value in DEFAULT_VALUE for this field upon upload.

that will be used to detTABLELOOKUP will d

DEFAUL E ield when it uploaded. This value will not be automatically inserted into the document when it is created, but will be used for

T_VALU Default value to be used for the f

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_ arameter is assigned to NAME Indicates the group the column/pOA_FLEX_CODE (Flex Code) Flexfield structure identifier. OA_CON a

spreadsheet. CAT_FLEX (Concat Flex) Concatenates the value entered for this column/parameter into one cell in

READ_ONLY value and it is placed in the context Y/N. If YES, then the user cant change this section of the document.

VAL_TYPE (Validat ESCFLEX, 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.

ion Type) Indicates the Validation Type. Valid values are DDESCFLEXCONTEXT, DESCFLEXSEG, GROUP,


21


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 (ValiMeaning)

VAL_ID_COL. These n in the worksheet.

d This is the column that contains the user value for values inare the values shown in the LOV show

VAL_DESC_COL (Valid c for values in VAL_ID_COL. These values are shown in the description section of the LOV.

Des ) Column that contains the description

VAL_OBJ_NAME (Valid je e values in the sheet. If VALTYPE = TABLE, then the name of the table to query is placed in this column (e.g.

TYPE =JAVA, then specify the Java class to call when .

ors.BneAccountingFlexValidator).

Ob ct) Table or Java class that is called to validat

FND_LOOKUPS). If VALvalidating the column (e.goracle.apps.bne.integrator.validat

VAL_ADDL_W_C (Valid h to add to a Table Validated column. W ere) Enter an additional Where ClauseDATA_TYPE Three values can be entered in this column. 1 = value in database/API must be a

API must be varchar; 3 = value in the DI will use this value to validate data in the

number; 2 = value in the database/database/API must be a date. Web Adocument.

NOT_NU b ADI uses this value to validate data in the document..

LL_FLAG Indicates that column in the DB or parameter for the API cannot be null. We

VAL_COMPO N(Valid Component)

NE T_APP_ID

Application ID of component to be called in BNE_COMPONENTS

VAL_COMPONEN retrieve T_CODE Name of Component from BNE_COMPONENTS that will be called tothe 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_EN LAB ED_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

r in the document and if the column is to be displayed in the Mapping and Layout UI.

Column header for field if in the Header region of the document. This value must be entered if the column header is to appea

Prompt A 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.

bove Column header for field if in the Lines

U ext Text to appear in the hint section for the column. This is the area between the ells and the Header.

ser Hint Tdata entry c

L hat will be entered in the TL Table anguage Language tS GE OURCE_LANGUA Language prompts will be translated from OA lex Num_FLEX_NUM (F ber) Flexfield structure identifier. OA_FLEX_APPLICATION(Flex Application)

_ID Flexfield structure identifier.

DISPLAY_ORDER Default order in which the columns/parameters are displayed in the document E RY lumns. This is the query that will be run to return the number of

periods to be displayed in the worksheet. XPANDED_SQL_QUE For expanded co

( ID that will be used to populate CREATED_BY and LAST_UPDATED_BY User ID)

4.2. Interface Columns Concepts

4.2.1. Table Validation/ LOV Retrieval

You can have Web ADI run a simple SQL statement to perform validation for a field during upload. Thiinformation can also be used to return a list of values within the document. Indicate a field will use Tabl

s e

VAL_OBJ_NAME: Enter the Table to be queried.

Validation by entering TABLE in VAL_TYPE.

Use the following columns to use a SQL statement for validation during upload:

VAL_ID_COL: Enter the column name for the query.


22

e

RESPID

$.USERID

o Session ID: $ENV$.SESSIONID

o Application ID: $ENV$. APPID

Use these columns if you want to provide LOVs that use the above SQL statement:

M ID ca w com

VAL_MEAN_COL (optional) alues in th o users in the LOV. ese me g values will be cum t; ADI will translate th

The following are example values for these columns:

VAL_ADDL_WC: Enter an additional where clause. Tokens can be used when forming the wherclause for your query:

o Profile Options: $PROFILES$.[Profile Option Name]

o Responsibility ID: $ENV$.

o Oracle User ID: $ENV

o Language: $ENV$.LANG

VAL_COMPONENT_CODE: Code of the component (from BNE_COMPONENTS_B) that will be used to retrieve the LOV. See Creating Components for more details.

VAL_CO PONENT_APP_ : Appli tion ID that as used to define the ponent. : If entered, v is column will be displayed t

Thcorresponding ID values during the upload process.

anin entered into the do en em to their

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) OR CURRENCY_CODE = 'STAT'

VAL_CO

COMPONENT_DE

OA_CURRENCY_CODE

VAAP

L_COMPONENT_PID

231

io4.3. Java Validat n/LOV Retrieval

This type of validation/LOV retrieval is u d ring m re complex queries ag ase. cant simpl e defined in the as ble Va ation. The Web ADI r

creates these Java classes. Luckily, the Web ADI development team has created classes tha d as p deve uickly crea n reat g Components for m

Indicate a field will use Java Validation by entering JAVA in VAL_TYPE. Enter the class name to be used for

sed for fiel s requi o ainst the databStatic SQL y b repository in Ta lid Integrator Develope

t can be usetemplates to hel lopers q te their ow . See C in ore information.

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.

4.4. Group Validation

Is validation on one field in your document dependent on the value of another? Do you have several fields that are validated the same way? If so, Group Validation is the answer. It is used to validate values from different


23

olves values in different columns being dependent on one

al fields is run. If one of the records has a different he field in addition to the group vali . Ste

Ident t Creat p

by inserti

Assign the dependent fields and the parent to the same group. Ent the parents VAL_OBJECT_NAME column.

A simple example f Journals Integrator (G r. An example of one bu in

olves values in different columns being dependent on one

al fields is run. If one of the records has a different he field in addition to the group vali . Ste

Ident t Creat p

by inserti

Assign the dependent fields and the parent to the same group. Ent the parents VAL_OBJECT_NAME column.

A simple example f Journals Integrator (G r. An example of one bu in

columns at once. This is done when validation invcolumns at once. This is done when validation invanother. 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 individu

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 individu

VAL_OBJ_NAME, that piece of validation code will be run for tdation ps to set up Group Validation:

VAL_OBJ_NAME, that piece of validation code will be run for tdation ps to set up Group Validation:

ify he dependent fields. ify he dependent fields.

e a arent record. It does not appear in the sheet, nor is uploaded. Identify the field as a parentng GROUP for VAL_TYPE.

e a arent record. It does not appear in the sheet, nor is uploaded. Identify the field as a parentng GROUP for VAL_TYPE.

er the Java class to perform the group validation in er the Java class to perform the group validation in o an instance to use group validation is the entered debit and credit columns in the GL

L_INTERFACE table). Validation on each field is dependent on the value in the othe o an instance to use group validation is the entered debit and credit columns in the GL

L_INTERFACE table). Validation on each field is dependent on the value in the othes ess rule is that the values in ENTERED_DR and ENTERED_CR must not both be null. s ess rule is that the values in ENTERED_DR and ENTERED_CR must not both be null.

INTERFACE_COL_NAME DISPLAYED_FLAG GROUP VAL_TYPE INTERFACE_COL_TYPE VAL_OBJ_NAME

ENTERED_DR Y ENTERED 1 ENTERED_CR Y ENTERED 1 ENTERED_PARENT oracle.apps.bne.validat

ors.enterDebitCreditvalN ENTERED GROUP 2

idator

A parent field must b ation. 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 she o oup Validation is assigned to it in VAL_OBJECT_NAME. All three fields are assigned to the ENTERED group.

An example where Group tion 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 verif e7 is Y. In addition to this check, REFERENCE7 TABLE validated and REFERENCE8 is JAVA validated.

e created to capture values for group valid

et f r editing. It merely acts as a placeholder for validation; the Java class to perform the Gr

Note: Remember, validation in addition to them being validated as part of a group.

can be run on individual columns

Validation is used in conjunction with valida

y that a period is entered when Referenc

INTERFACE_COL_NAME DISPLAYED_FLAG GROUP VAL_TYPE INTERFACE_COL_TYPE VAL_OBJ_NAME

REFERENCE7 Y REVERSAL TABLE 1 FND_LOOKUPS REFERENCE8

iodvalidator Y REVERSAL JAVA 1 apps.bne.validators.per

REVERSAL_PARENT N REVERSAL GROUP 2 apps.bne.validators.revtableformattingvalidator

Just st example, a parent is created and assigned to a group with the dependent fields. This field will be displayed to Java class t e group validation is assigned to

V M ditio Gro d N T ted FND_LOOKUPS (VAL_ID_COL and VAL_ADDL_Wd with ervalida

as in the lanot be uploaded, nor will itthe parent in against

users. The n to being

o perform tup Validate

C not shown). REFERENCE8 is being JAVA

h, REFEREAL_OBJ_NA E. In ad CE7 is being ABLE valida

validate the p tor class.


24

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 w g is done to y F alid

4.5.1. Enter records for the Key Flexfield Segments.

Indicate Key Flexfield segments by entering KEYFLEXSEG in VAL_TYPE. ist in the Table/API. They are not

Assign the segments to a group.

his field will be selected in the mapping UI when the user

he

in OA_FLEX_CODE.

oracle.apps.bne.integrator.component.BneOAFlexComponent

Enter OA_FLEX for VAL_COMPONENT_CODE (not shown in example below). This value is required to enable List of values for the Key Flexfield

Enter your product ID for VAL_COMPONENT_APP_ID. Example:

this. The follo in enable Ke lexfield v ation/LOV:

These fields are not displayed in the spreadsheet but exdisplayed because Web ADI does not know what KFF segments from the interface table to display when creating the document.

4.5.2. Create a parent field for the Key Flexfield group.

Set INTERFACE_COL_TYPE = 2 since this field does not exist in the interface table.

Set DISPLAY_FLAG = Y since twants the key flexfield to be included in the worksheet.

Add this field to the group containing the segment fields.

Enter KEYFLEX for VAL_TYPE to identify it as the parent. Enter oracle.apps.bne.integrator.validators.BneKFFValidator in VAL_OBJ_NAME. This is t

class that will validate the Key Flexfield.

Enter the code that is used to retrieve the Key Flexfield structure 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: 1. APPLICATION_ID: Your application ID

2. COMPONENT_CODE: OA_FLEX

3. COMPONENT_JAVA_CLASS:

INTERFACE_COL_NAME

DI LASP YED_FLAG

GROUP VAL_TYPE INTERFACE_COL_TYPE

OA_FLEX_CODE

OA_CONCAT_FLEX

VAL_OBJ_NAME

SEGMENT1 N ACCOUNT KEYFLEXSEG 1 SEGMENT2 N ACCOUNT KEYFLEXSEG 1 SEGME NT3 N ACCOUNT KEYFLEXSEG 1


25

INTERFACE_COL_NAME

DI LASP YED_FLAG

GROUP VAL_TYPE INTERFACE OA_FLEX OA_CONCAT_ VAL_OBJ_NA_COL_TYPE _CODE FLEX ME

ACCOUNT_FLEX_FIELD

Y oracle.apps.bne.validators.BneKFF

ACCOUNT KEYFLEX 2 GL# N

Validator

4.6. Uploading Code Combination Identifier For Key Flexfield Values

There may be a case where you want to display Key Flexfield values to user within the worksheet, but upload the code Combination Identifier (CCID) that represents the Key Flexfield values to a single column in the interface table.

.6.1. e a parent field for the Key Flexfiel

The INTERFACE_COL_NAME should be the column in your interface tab e that youre uploading t ID o an API, the UPLOAD_PARAM_LIST_ITEM_NUM value s h n ber in the parameter ist of the parameter that captures the CCID.

Set DISPLAY_FLAG is ld will be s mapping UI r wants the key flexfield to be included in the worksheet.

Set INTERFACE_COL_TYPE = 1 since the key flexfield segments displayed in the worksheet will be uploaded as a single value to this column.

parent field (youll later assign the segments to this

in VAL_OBJ_NAME. This is the

ct

_CLASS: rator.component.BneOAFlexComponent

ENT_CODE (not shown in example below). This xfield

4.6.2. Enter records for the Key Flexfield Segments.

4 Creat d.

lhe CC

hould matc to. If uploading tthe sequence um l

= Y since th fie elected in the when the use

Enter a new GROUP_NAME for the group).

Enter KEYFLEXID for VAL_TYPE to identify it as the parent. Enter oracle.apps.bne.integrator.validators.BneKFFValidator

class that will validate the Key Flexfield

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 produID:

1. APPLICATION_ID: Your application ID


3. COMPONENT_JAVAoracle.apps.bne.integ

Enter OA_FLEX for VAL_COMPONvalue is required to enable List of values for the Key Fle

Enter your product ID for VAL_COMPONENT_APP_ID.


26

The INTERFACE_COL_NAME needs to be in the following format: [Interface Col Name

Set DISPLAY_FLAG = N. These fields are not displayed in the mapping UI. o not exist in the interface table or API.

the parent segment belongs to.

Example:

Indicate Key Flexfield segments by entering KEYFLEXIDSEG in VAL_TYPE.

of Parent field]_SEGMENT1........SEGMENT2..SEGMENTn.

Set INTERFACE_COL_TYPE = 2 since these fields d

Assign the segments to a the same group

INTERFACE_COL_NAME

DISPLAYED_FLAG

GROUP VAL_TYPE INTERFACE_COL_TYPE

OA_FLEX_CODE

OA_CONCAT_FLEX

VAL_OBJ_NAME

ACCTCCID_SEGMENT1

N ACCOUNT KEYFLEXIDSEG

2

ACCTCCID_SEGMENT2

N ACCOUNT KEYFLEXIDS 2 EG

ACCTCCID_SEGMENT3

N ACCOEG

UNT KEYFLEXIDS 2

ACCTCCID Y N oracle.apps.bne.validators.BneKFFValidator

ACCOUNT KEYFLEXID 1 GL#

4.7. Descriptive Flexfield Validation/LOV Retrieval

Web ADI suppo Laccomplish this. Th escriptive Flexfield validation/LOV:

4.7.1.

FF segment by entering DESCFLEXSEG in VAL_TYPE

b ADI does not know what d. The Flexfield structure is returned once

1 since the segments exist in the table/API.

4.7.2. Create a p n the document, but does not exist in the table/API

Set P Set INT

entify the Key DFF structure.

rts ist of Values and the validation of Descriptive Flexfields. Group Validation is used to e following is done to enable D

Create records for each DFF segment.

Indicate a field is a D Set DISPLAY_FLAG to N for all segments. This is because We

DFF segments to display when the sheet is createthe 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.

INTERFACE_COL_TYPE should be set toarent record for the group. It will be visible i

DIS LAY_FLAG to Y.

ERFACE_COL_TYPE to 2.

Assign the parent to the group its segments belong to. Set OA_FLEX_CODE to the code that is used uniquely id


27

Enter Y for OA_CONCAT_FLEX. The values for all the DFF segments will be concatenated into the context column in the document.

er DESCFLEX for VAL_TYPE. t his of its DFF group.

Enter a ators.BneDFFValidator for VAL_OBJECT_NAME. This is t tes D segments

Insert Record into BNE_CONTENTS_B:


COMPONENT_CODE: OA_FLEX

This entry is required to enable List of Values.

E r your product I MPONENT_A4.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 t and exists in the interface table.

Assign to the group.

Enter N for OA_CONCAT_FLEX. Enter DESCFLEXCONTEXT for VAL_TYPE. This value indicated that this field is the

Insert Record into BNE_CONTENTS_B:

COMPONENT_JAVA_CLASS: oracle.apps.bne.integrator.component.BneOAFlexComponent

he context

Ent This indica es that t field is the parent

oracle.apps.bne.integrator.v lidhe Java code that valida FF .

2.

3. COMPONENT_JAVA_CLASS: oracle.apps.bne.integrator.component.BneOAFlexComponent

Enter OA_FLEX for VAL_COMPONENT_CODE.

nte D for VAL_CO PP_ID.

documen

Enter Y for DISPLAY_FLAG. This field must be available to allow the user to enter a value to retrieve the DFF structure.

Enter 1 for INTERFACE_COL_TYPE.

Enter the unique code for the DFF structure in OA_FLEX_CODE.

context segment for the group.



3.

Enter OA_FLEX in VAL_COMPONENT_CODE. This will enable the LOV for tfield.

Enter your product ID for VAL_COMPONENT_APP_ID.


28

Example:

INTERFACE_COL_NAME

DISPLAYE_FLAG

GROUP VAL_TYPE INTERFACE OA_FLEXD _COL_TYPE _CODE

OA_CONCAT_FLEX

VAL_OBJ_NAME

ATRRUBUTE 1 N JNLLINEDFF DESCFLEXSEG 1 ATTRUBUTE 2 N JNLLINEDFF DESCFLEXSEG 1 ATTRIBUTE3 N JNLLINEDFF DESCFLEXSEG 1 JOURNAL_LFF

EX 2 GL_JE_LINES

Y .apps.bne.valid INE_D Y JNLLINEDFF DESCFL

CONEXT NEDFF DESCFLEXCONTEXT

1 GL_JE_LINES

N Y JNLLI

4.8. Replicating Fields

Web ADI can upload a v meters. This involves identifying a master field (i.e. the value from this field will be replicated), then referencing that field reatBNE_INT follows:

alue entered for a field in a document into multiple interface columns/API para

when c ing records for the replicating columns in BNE_INTERFACE_COLS_B. Enter records in ERFACE _COLS for the replicated interface columns as

REQUIRED_ DISPLAY_FLAG DEFAULT_TYPEFLAG DEFAULT_VALUE

Y N $table$.InterfaceName.InterfaceColName TABLELOOKUP

4.9. aluesDefault V

Default in BNE_INTERFACE_COLS_B are generated at upload time. A default value will be uploaded for a column if a value for itDEF If you wish _TYPE and DEFAULT_VALUE in BNE_LAYOUT_COLS_ALL; See se

Default valucan all be uscolumn has four pos

SQL: DEFAULT ENVIRONMENT: DEFAULT_VALUE is an environmental variable to be inserted into the document. Valid

variables in DEFAULT_VALUE are DATABASE, OAUSER.ID, SOB.Set.Of.Books.Name, LANGUAGE, and SYSDATE

CONSTANT: DE AUL he document as a default value. JAVA: DEFAUT _VAL run to generate a default value.

4.10. Expanded Co

values set does not exist in the document. Enter values in DEFAULT_TYPE and

AULT_VALUE in BNE_INTERFACE_COLS_B to have Web ADI generate default values at upload time. to automatically place default values in the document when it is created, use DEFAULT

ction 9.1.7 for more information.

es can be stored in metadata. Alternatively, SQL statements, environmental variables, and Java code ed to generate default values. DEFAULT_TYPE describes the value in DEFAULT_VALUE. This

sible values:

_VALUE is a SQL statement to be run to derive the default value in the document.

F T_VALUE itself will be inserted into t

L UE contains a Java class that will be

lumns

You may ha here example, a b(PERIOD1_AMOUNrange of periods the columns functionalitretrieve the list of co

ve a case w the number of columns in the document must be determined at run time. Forudget integrator uploading to an interface table containing 60 period columns

T, PERIOD2_AMOUNT,PERIOD60_AMOUNT) would require this functionality. The user requires in the document could not be determined at design time. The expanded y allows an integrator developer to specify a SQL statement that will be used at run time to lumns and column headers. Follow the instructions below to enable expanded columns.


29

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.1. Assign each column to a GROUP called PERIODAMTS

4.10.1.2. nter EXPANDEDSQLSEG for VAL_TYPE.

4.10.1.3. apping Enabled = Y.

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.2.1. Group Name=PERIODAMTS

4.10.2.2. Val Type = EXPANDEDSQL

4.10.2.3. OA Concat Flex = N

4.10.2.4. Type = 2

4.10.2.5. Display = Y

4.10.2.6. Mapping Enabled = N

4.10.3. Create a Layout that includes the parent segment by selecting Define Layout from the PHP. Select your integrator and include the parent segment in the lines region of the layout.

4.10.4. Insert into BNE_INTERFACE_COLS_B. EXPANDED_SQL_QUERY for the parent record.

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:

SELECT PERIOD_NAME, PERIOD_NUM FROM GL_PERIOD_STATUSES WHERE PERIOD_YEAR = 2002 AND APPLICATION_ID = 101 AND SET_OF_BOOKS_ID = 1 AND PERIOD_NUM >= $PARAMS$.PERIODFROM AND PERIOD_NUM


31

ompomp5. Creating C5. Creating C onents onents

A component is an object field in a document. They are the values specified in VAL_C E in BNE_INTERFACE_COLS_B.

5.1. Creating Ta

You must create a component for every Table Validated field requiring an LOV within the document. A Java has been provided to offer this functionality, but metadata must be entered for each LOV to handle

h as g steps to create a Table Validated Component.

5.1.1. Creat

defined in metadata that provides a list of values for a OMPONENT_APP_ID and VAL_COMPONENT_COD

Attention: You ADI SDK is functionally se a URL or a value in the worksheet o restricted values.

must make sure that the code you plug into the Webcure. Users must be prevented from manipulating that would give them access t

ble Validated Components

classproperties suc table headers and window captions. Use the followin

e Component

Insert a record int ord registers the component and tells Web ADI what Jav orming validation.

o BNE_COMPONENTS_B and TL tables. This reca class to reference when retrieving the LOV and perf

APPLICATION_ ID The identifier for your applicationCOMPONENT_C ion ID for the ODE A unique code within your applicat

component. OBJECT_VERSION_NUMBER Set this to 1 COMPONENT_J neOAValueSet AVA_CLASS Set this to BPARAM_LIST_APP_ID The identifier for your application PARAM_LIST_CODE Se t this to the code you create in 5.1.2 LANGUAGE Set this to US SOURCE_LANG Set this to US USER_NAME ly not used by the This user value is current

application.

reat

5.1.2. C e a Parameter List for the Component

This list contains a by the LOV component. Lists have a one to one relationship a omponents.

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 comm

ist by pressing Add Another Row.

ll of the parameters required with Table Valid ted c

ents if needed. Press Save when finished.

5.1.2.2.

Add the Following Parameters to the Parameter l


32

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 N_ALIAS parameter

efinition under your own application ID and use Copy the 231:TABLE_COLUMdthe copy for this parameter.

Parameter Name table-select-column Value Enter the

BNE_INTERFACE_COLS_B.INTERFACE_COL_NAME of the column you wish the selected LOV to update in the document

Description Parameter Definition r

and use the opy for this parameter

Copy the 231:TABLE_SELECT_COLUMN parametedefinition under your own application IDc

Parameter Name table-columns Value he query specified in

_COLS_B to be displayed in the lOV. That is, enter one or all values specified in VAL_DESC_COL, VAL_ID_COL VAL_MEAN_COL VAL_MSG_COL. This is a comma delimited list.

Enter the select columns in tBNE_INTERFACE

Description Parameter Definition Copy the 231:TABLE_COLUMNS 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: Parameter Name table-block-size Value etermines the

umber of records that will be displayed in the LOV (Use default from definition This dnat one time)

Description Parameter Definition Copy the 231:TABLE_BLOCK_SIZE parameter

use definition under your own application ID andthe copy for this parameter.

Default used when this parameter is

10 not added

to the list Parameter Name -height windowValue (Use default from definition this indicates the

height of the display window) Description Parameter Definition the 231:WINDOW_HEIGHT parameter Copy


33

definition under your own application ID and use the copy for this parameter.

Default used when this parameter is not added to the list

450

Parameter Name window-width Value (Use default from definition this indicates the

width of the display window) Description Parameter Definition

ation ID and use py for this parameter.

Copy the 231:WINDOW_WIDTH parameter definition under your own applicthe co

Default used when this parameter is not added to the list

350

Parameter Name window-start-position Value (Leave blank to use default this is where the LOV

ow will first appear on the screen). windDescription Parameter Definition Copy the 231:WINDOW_START_POS parameter

definition under your own application ID and use the copy for this parameter

Default hen used w this Windows default parameter is not added to the list The parame tions y le validated co 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.

ter defini ou created for the parameters above can be re-used when creating more than one tabmponent within your application.

Parameter Name table-headers Value Le

thi mn headers tha

ave blank to use default in parameter definition s is Comma-delimited list of table colut will appear in the LOV screen.

Description Parameter Definition Pre te definition ss the Definition Button to crea Definition: Name Table-headers {Name of Interface Column} Source (Integrator Name):Components Category Data Des n n headers. This

parameter has an individual parameter definition so criptio Comma-delimited list of table colum

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 Translat Checked able Ma z 100 x Si e


34

Display Size 100 Name window-caption Val ult in parameter definition

on bar) ue (Leave blank to use defa

this is the title to be placed on window captiDescription Enter meaningful description Parameter Definition Press the Definition Button to create definition Definition: Name aption {Name of Inter face column} Window-cSource (Integrator Name):Components Category Data Description This is what is displayed in the window caption Data Type String Default Value Ent he LOV

wer what you want to be displayed in t

indows caption. Store as Translatable Checked Max Size 100 Display Size 100

5.1.3. Assign Component to a field in BNE_INTERFACE_COLS_B

5.1.3.1.

ta.

ate the VAL_COMPONENT_CODE and VAL_COMPONENT_APP_ID (Valid Component) columns in the spreadsheet create

Identify the Interface Column in BNE_INTERFACE_COLS_B that will use the component. You can use the Web ADI Interface Cols Integrator to download your interface column metada

5.1.3.2. Updd by the Web ADI Interface Cols Integrator.


INTERFACE_CODE Object Code of the Interface. Select INTERFACE_CODE, INTERFACE_NAME from BNE_INTERFACES_B to get this value.

SEQUENCE_NUM d that is assigned to the same Application ID/ INTERFACE_CODE. So you could have the same SEQUENCE_NUM for two Unique ID for every recor

records in this table, but they would have to be assigned to different AppID/Interface Code combinations.

VAL_COMPONENT_CODE (Valid Component)

Key to Component

VAL_COMPONENT_APP_ID Application ID that was used to create the above component

5.2. Creating JAV

Your field may require an LOV or validation that is more complex than Table Validation. Valid fields could depend on a number of parameters, the creation of a Java Validat ted field involves the following steps:

9 Create Java Class

A Validated Components

including some entered or existing in the document. Complex business rules will requireed record in BNE_INTERFACE_COLS_B. Creating a Java valida


35

9 Enter a record for th

9 Create Parameter List for the component

9 Create parameter de

A uired by the class to the Parameter List

9 Assign Component nent key in VAL_COMPONENT_CODE, an application ID in BNE_VAL_COMPONENT_APP_ID and entering the Java Class in VAL_OBJ_NAME.

Jav a s 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

les to be used for the following purposes:

o det o the database.

There are three main Java classes associated with Java Validation:

1.1.1.1 SQL Java Class

e component into BNE_COMPONENTS_B/_TL

finitions for the class

9 ttach Parameters req

to a column in BNE_INTERFACE_COLS_B. This includes putting the compo

a v lidation includes the following two types of functionality; provide List of Value

Validators respectively.

Java Validation allows business ru

To determine the data to be displayed to a user in an LOV. T ermine whether a value is valid prior to uploading it t

This class contains all of the SQL queries required for Java Validation: including LOVs and Upload Validators.

1.1.1.2 Validator Java Class

This class contains all the business logic for Java Validation: including LOVs and Upload Validators. The LOV code is separate to the Upload Validator code, but the code for bothis maintained in this class.

For more complex solutions where the validation of one int

erface column is conditional

Foruplo , or can be used at Upload time to ensure that

1.1.1.3 Component Java Class

upon the validation of one or more other interface columns, a Group Validator will needto be implemented.

example: if any one of three columns is required to contain a value at the time of ad but none of the columns is defined as a required column, then a Group Validat

one of the three columns contains a value.

This class contains all the business logic and setup information for generating the List of Values (LOV) page in the Web ADI document. This class is not required for the

tadata corresponding to the LOV and base schema.

implementation of an Upload Validator.

As part of the Java Validation implementation, meUpload Validator must be seeded in the BNE data

Sample metadata and sample Java Classes are included in the Appendices of this document.


36

hat 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 Validator.

1.1.1.4 Naming Standard

This documentation assumes t

implement an LOV or Upload

s

The following naming standard is a guideline for naming your Java classes:

lication short name, e.g. Bne, Gl, etc.

omponent depending on the type of class being written.

Use the same name for all three classes that make up the LOV and/or Upload Validator. ent for which the Java

Validation is being implemented.

e.g. ApplFieldNameSQL, ApplFieldNameValidator, ApplFieldNameComponent; or

BnePeriodNameSQL, BnePeriodNameValidator, dNameComponent

ard of InitCaps for your class names, as shown in the example above.

Prefix each class name with your app Suffix with SQL/Validator/C

This usually includes the name of the field in the Web ADI docum

BnePerio

Use the Java stand

SQL Java Class

o the Interface Column, and all the SQL queries required to perform the Upl 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

class Appendix A), when validating the SQL queries:

1. When uploading eed to run a query to confirm that the Accounting Date falls within the Period.

B s are required to ensu curate and meaningful error message is displayed to the user.

F idator that incorpo usiness 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 th

Example 1 Generic example:

IF A and B THEN

This class contains all the SQL queries required to generate the List of Values (LOV) applicable t

oad Validation for the same Interface Column. Usually these queries

more queries are required to validate a single field.

For example (as per the BneOAPeriodNameSQLPeriod Name column in a GL Journal, you may need the following

an Accounting Date and a Period Name, you n

2. It is also necessary to check that the Period is valid.

oth querie re that a more ac

or a Java Val rates several b

is can be done:


37

Generate List of Values C

Generate List of Values D

END IF

Example 2

IF an Accounting Date has been entered in the spreadsheet THEN

G Periods that include the Accounting Date

ELS

Generate a List of all Open or Future Enterable Periods

E

1.1.1.5 Implementing the SQL Java Class

ELSE IF A

ELSE

Generate List of Values E

Period Name example:

enerate a List of all

E

ND IF

Th Co

Fo wing signature should be used for

public BneApplFieldNameSQL(BneWebAppsContext context,

For a Validator/LOV requiring two or more SQL queries, the following signature should be

neWebAppsContext context, int queryNumber,

The parameters for the SQL Java class Constructor are as follows:

is class must be written as a public class that extends BneBaseSQL. The class only requires anstructor method.

r a Validator/LOV requiring only one SQL query, the follothe Constructor:

String extraSQL)

used for this Constructor:

public BneApplFieldNameSQL(B String extraSQL)

Parameter Value, Description

Context 800, this is the Application ID for Oracle HR. queryNumber Object version. extraSQL


38

context 1.1.1.6

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. each

default switchq ry

For e

query.append(SELECT );

case 2: query.append(SELECT ); break;

A switch statement is used to hold the different queries using a number to representcase. It is important to include a case in the statement to handle any invalid

ue numbers.

xample:

switch (queryNumber) { case 1: 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 ADdocument. This is only used by the Uplo

I ad validator, and is appended to the appropriate

query to restrict the results using the user-selected value.

Th

StringBuffer

The SQL queries in this class will be run:

Values to be displayed in the List of Values page; and

eria of the query limiting the g

e pseudocode for the SQL Java class Constructor is as follows: - Build up the query in a StringBuffer - Append the string in the extraSQL parameter to the

if the extraSQL parameter is not null - Call the BneBaseSQL.setQuery method to prepare the SQL query

To summarise how this class will be used:

Firstly to generate the List of Secondly, to validate the user-selected value at upload time.

For Upload Validation extra SQL is appended to the Where critquery results to values matching the user-selected value. Therefore, the value beinuploaded is only valid if one or more rows are returned by the query, and invalid when no rows are returned.


39

Validator Java Class

The Web ADI platform has been designed to acompdatab

Some examples of the complex logic that can be incorporated into the Java Validators:

that will be done depending on the profile option value.

the database can be used within your valida mn(s) in the Web ADI document.

There Java validators: Field Validators and Group Validators.

Fie

llow the use of Java Validators to allow more lex logic to be used to validate the data in a spreadsheet before it is uploaded into the ase.

Profile options determine the validation

Other system setup m anything that can be queried frotor class to assist in validating the interface colu

are two types of

ld 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 enter individual interface column.

Group Validators

ed in the spreadsheet can be used to help validate the

An interface column can be pa 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.

1.1.1.8 Implementing a Field Validator Java Class

rt of a group. All columns that form part

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.


40

Metho Upload Validator ds that MUST be implemented for an

startupValidator

This method to perform setup steps that only need to be performed once. For example, look up a d therefore only

The signature for

pu(BneWebAppsContext context, Hashtable requestParameters, Hashtable columnValues)

method is called once at the beginning of the Upload Validation process. Use this

profile option value. This value is not different for each row of data, anneeds to be derived once.

this method is as follows:

blic BneUploaderMessage[] startupValidator

validateColumn This metco lue that was validated (in the same upload), t ure for this method is as follows:

dateColumn t context,

BneUploadColumn currentColumn)

hod is called once for each different value being uploaded for the interface lumn. If the value being validated is the same as the last va

he validation will not occur again. The signat

public BneUploaderMessage[] vali(BneWebAppsContex Hashtable requestParameters, Hashtable columnValues,


41

method is as follows:

- Any other required values from the columnValues hashtable - Any other required values (derived within the class)

- Else - Return an uploadError message in the BneUploaderMessage array. - End if

or

The logic for this

- Get the currentColumn value - 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)

- If the SQL Result Set contains 1 or more records - Set the record as FineGrainValid

shutdownValidatThis method is called once at the end of the Validation process. Ensure that any SQL

rMessage[] shutdownValidator()

Method t can be tio

handles are closed in this method. The signature for this method is as follows:

public BneUploade

s tha op mplemented nally i

The following metho an be op ual field validator:

finalValidation

d c tionally implemented for an individ

This method is processed after all rows have bbe carried out that for the entire set of rows in the Upload document, if required. The

een validated. This allows for validation to

meters)

Useful methods provided by the upload interfaces

signature for this method is as follows:

public BneUploaderMessage[] finalValidation (BneWebAppsContext context, Hashtable requestpara

The following prot hods are available for use within your validator class: ected met

uploadError

This method can be used to simplify the formatting of an Upload Error message. This is an error message and will preventpa ould explain what the error is and how the is as follows:

protected BneUploaderMessage[] uploadError (BneUploadColumn currentColumn,

msgStr,

the upload from occurring. A message should be ssed to this method in the msgStr parameter. This message sh

error can be fixed. The signature for this method

String String className)


42

uploadException

This method can age. This is an error message and will prevent the upload from occur