(WEB ADI Release 12)

(February 2014)

Introduction This paper will explain detailed solutions on how to use WEB ADI to convert legacy data to Oracle Application. This papers focus is on best practices for preparing data for upload, creating documents and defining layouts, data upload and upload reconciliation.WEB ADI Overview

Web Applications Desktop Integrator is a tool that leverages the standard desktop applications to perform some of the Oracle E-Business Suite task. The Web ADI brings Oracle E-Business suite to the desktop where familiar desktop tool like Excel can be used to create spreadsheet, enter and modify data in the spreadsheet and finally upload the data into the Oracle Applications. Web ADI can be very useful for the users who are experienced with Excel and will like to use excel to enter the data related to Oracle Applications. These users can use the special features of excel i.e. copy, paste, drag cells to increment and various arithmetic functions to optimize their business task and increase their productivity. Data that is entered into the spreadsheet can then be finally be uploaded in to the Oracle Applications with or without validation.Key Concepts

Integrator - This is the definition that stores the information about the action the user wishes to perform. For example, downloading specific data to a spreadsheet for viewing or to modify and upload back to the database.

API - Application Programming Interface. This is the pl/sql interface by which data is validated and uploaded into Oracle Application. You would associate an API with an integrator if it was intended to either create new data in the application or update data that had been previously downloaded.

View - A view is an object by which you can query data on a table or tables. If the action you are intending to perform involves downloading data, you must associate a view with the integrator. If you are using Create style APIs, you do not require a view. You can elect to use a seeded view, for example, PER_PEOPLE_V, to use with your integrator. However, if the integrator is for updating data, then it is recommended that you create your own views and any other In/Out parameters used by your chosen API.

One thing to beware of is the use of Aliases in views if you are downloading from a form. For example, if you use an alias for Applicant_Name called Starter, and then use a restrictive query in the form on Applicant Name before running the integrator in Web ADI, you will get the following error in the BNE log. BneBaseSQL.executeBneQuery: Exception while running query. Error Code: 904, Message: ORA-00904: "APPLICANT_NAME": invalid identifier. This column APPLICANT_NAME has been overwritten by the alias in the definition loaded into the BNE tables.

Layout - This is where the user selects the columns to be displayed in the spreadsheet or Word document from the API and/or View used by the integrator. An integrator can have more than one layout defined for it. You can choose which one to use when you create your document.

Mapping - The mapping definition links the data source to the API columns. If no view is specified against the integrator or no text file used to load data, then no mapping is needed. When the data source is a view, the mapping is created automatically, however if a text file is being used then a mapping needs to be manually defined to associate each column in the file (source) to the relevant API parameter (target). WEB ADI and MS 2007To use WEB ADI with Microsoft 2007, macro settings need to be enabled, and browser settings need to be modified.

1. Click the Office Button (top-left button in the window)2. Click the Microsoft Excel Options button.3. Click Trust Center in the menu on the left.4. Click Trust Center Settings in the window on the right.5. In the new window that opens click Macros in the menu on the left.6. Under 'Macro Settings' check 'Disable all macros with notification'.7. Under 'Developer Macro Settings' check 'Trust Access to the VBA project object model'.8. Click 'OK'9. Click 'OK'Creating an IntegratorWhat? How? Who?

What? The creation of an integrator is a task that would be performed by a System Administrator who would need to analyze the business requirement, and then decide in technical terms how to achieve it. For example, if an upload or create type integrator, what API should be used? Also if not a create type integrator which view should be used to access the data in the database? If you create your own view, you can improve the quality of the document by formatting the columns in the view.

Please note that there is no maintenance integrator so once the integrator has been uploaded, it is not possible to edit it if a mistake has been made.

How? A detailed step by step guide on creating different integrators is included in the next section. However, in the HRMS Application, consideration has to be given to how the integrators are accessed. There are two types of Integrators, an Application Integrator and a Standalone Integrator. Application Integrators are linked to specific forms. The user uses the form in the Professional User Interface (PUI) to query data, and then exports that data using the Export Data icon. The standalone integrator is created with a form name of GENERAL. This then allows the integrator to be run from a self service menu by adding the function HRMS Create Document.

Who? You control access to all HRMS Web ADI integrators using form functions. Existing form functions for seeded integrators are supplied and can be added individually to navigator menus or in their entirety by adding the submenus, HR ADI Seeded Integrator Form Functions and HR ADI Skills Seeded Integrator Form Functions.

For user-defined integrators, you must create form functions and associate them to an integrator. You can be quite flexible on how to do this. A detailed step by step guide on creating form functions and associate them to an integrator is included in the next section.

A Step by Step Guide to Creating HRMS Integrators Define a Download style IntegratorThis example demonstrates how to create a reporting integrator1. Login to the application and navigate to Desktop Integrator -> Create Document2. Select Integrator HR Integrator Setup. Click on Next button3. Select Viewer as Excel 2007 and DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button.4. Choose None for Content to open empty document. Click on Next button. 5. On Document Creation Review page, Click on Create Document button and open file, A Processing window will open and a Confirmation window will advise when document has been created.6. In the blank spreadsheet enter a value for each of the columns as follows.Metadata Type - Select List of Values from Oracle menu or right click on mouse. Choose DOWNLOAD

Application Short Name - Choose your Application Short Name (XXCUST)

Integrator User Name - Enter a name for your integrator (XX Test Download)

View Name - View which downloads the data on excel sheet (XX_TEST_EMP_V)

Form Name - GENERAL7. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. Define a Update style IntegratorThis example demonstrates how to create an integrator that will allow the download the data and upload it to oracle application.1. Login to the application and navigate to Desktop Integrator -> Create Document2. Select Integrator HR Integrator Setup. Click on Next button.3. Select Viewer as Excel 2007 and DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button.4. Choose None for Content to open empty document. Click on Next button. 5. On Document Creation Review page, Click on Create Document button and open file, A Processing window will open and a Confirmation window will advise when document has been created.6. In the blank spreadsheet enter a value for each of the columns as follows.Metadata Type - Select List of Values from Oracle menu or right click on mouse. Choose UPDATE

Application Short Name - Choose your Application Short Name (XXCUST)

Integrator User Name - Enter a name for your integrator (XX Test Update)

View Name - View which downloads the data on excel sheet (XX_TEST_EMP_V)

Form Name - GENERAL

API Package Name - Package which validate and upload data to Oracle (XX_TEST_UPDATE)

API Procedure Name: - Procedure of the package (UPDATE_TEST)

Interface User Name - Enter a unique name (XX_TEST_UPDATE_INTF)

Interface Parameter List Name - Enter a unique name (XX_TEST_UPDATE_PARAM)

API Type - Select List of Values from Oracle menu or right click on mouse. Choose PROCEDURE7. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. Define a Create style IntegratorThis example demonstrates how to define an integrator that will allow the upload of new records into Oracle Application from spreadsheet and also using a text.

1. Select Integrator HR Integrator Setup. Click on Next button.2. Select Viewer as Excel 2007 and DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button.3. Choose None for Content to open empty document. Click on Next button. 4. On Document Creation Review page, Click on Create Document button and open file, A Processing window will open and a Confirmation window will advise when document has been created.5. In the blank spreadsheet enter a value for each of the columns as follows.Metadata Type - Select List of Values from Oracle menu or right click on mouse. Choose CREATEApplication Short Name - Choose your Application Short Name (XXCUST)

Integrator User Name - Enter a name for your integrator (XX Test Create)

Form Name - GENERAL

API Package Name - Package which validate and upload data to Oracle (XX_TEST_CREATE)

API Procedure Name: - Procedure of the package (CREATE_TEST)

Interface User Name - Enter a unique name (XX_TEST_CREATE_INTF)

Interface Parameter List Name - Enter a unique name (XX_TEST_CREATE_PARAM)

API Type - Select List of Values from Oracle menu or right click on mouse. Choose PROCEDURE6. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. Define a Download Integrator with an Additional Where clauseThis example demonstrates how to define an integrator that will allow you to run ad hoc queries in the application. In this case running query on Last Name.

1. Login to the application and navigate to Desktop Integrator -> Create Document2. Select Integrator HR Integrator Setup. Click on Next button3. Select Viewer as Excel 2007 and DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button.4. Choose None for Content to open empty document. Click on Next button. 5. On Document Creation Review page, Click on Create Document button and open file, A Processing window will open and a Confirmation window will advise when document has been created.6. In the blank spreadsheet enter a value for each of the columns as follows.Metadata Type - Select List of Values from Oracle menu or right click on mouse. Choose DOWNLOAD

Application Short Name - PERIntegrator User Name - Enter a name for your integratorView Name - PER_PEOPLE_VForm Name - GENERAL7. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload.8. Create restrictions for Standalone Query by Creating a Document using HR Create Standalone Query Integrator. This links an additional where clause to the integrator you have already created. Remember to leave Reporting checkbox un-ticked. Enter values for the following fields in the spreadsheetIntegrator Name - Name entered above

SQL Where Clause - where last_name=$PARAM$.last_name

1st Parameter Name - last_name

1st Parameter Type - Varchar2

1st Parameter Prompt - Last Name equals

N.B. Add 2nd, 3rd params, etc as required9. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload.A Step by Step Guide to Define Layouts

This example demonstrates how and which columns to be displayed in the spreadsheet. For each integrator there must be at least one layout.1. Login to the application and navigate to Desktop Integrator -> Define Layout2. Select Integrator for which you want to define layout. Click on Go button.3. Select an existing layout to update or create a new layout by Click on Create button.4. Enter Layout Name and number of headers to place across the top of the document. Click on Next button.5. Select the fields to appear on the layout, set defaults for the fields, and select the placement of the field as context, header, or line item. Click on Next button.6. Set properties for the layout components including field width or column span, hidden or unhidden, and position. Click on Apply button.Layout Field Options______________________________________________________________________________

Fields Description

______________________________________________________________________________Placement Defines the location of the field on the spreadsheet. Choices are Context, Header, and Line. In your spreadsheet: Context: Appears at the top of the spreadsheet as read-only, contextual information Header: Fields whose values do not change for every record you are uploading. This region appears above the line region in the spreadsheet. If you specified multiple headers, select the one you wish the field to display in (for example: Header 1, Header 2, or Header 3. Line: Fields whose values change for every record that is uploaded to Oracle Applications. The rows of data in this region represent every record that will be uploaded.Default Types Note that some fields will have defaults predefined.Default Type - Constant Used when the text entered in the Default Value field is used as the default value in the spreadsheet.Default Type - Environment Used to reference an environment variable when setting a default for a field. Values are as follows: sysdate: System date database: Name of the current database oauser.id: ID of your current Oracle Applications userDefault Type - Parameter Used to reference a parameter that your system administrator stores in the form function (Self Service Link) that you use to access the Create Document flow. The parameters that can be referenced are specific to each integrator.Default Type - SQL Used to run a SQL statement to determine the default for the field. Web ADI runs the SQL statement entered in the Default Value field and automatically populates the spreadsheet with the results. If more than one value is returned from the query, it uses the first value.

You can use the following tokens in the SQL statement for the Default Value field: $profiles$.profilename: Returns the value for the current user's profile when you enter the name of the profile option. $env$.userid: Returns the current user ID. $env$.appid: Returns the current application ID. $env$.respid: Returns the current responsibility ID. $env$.language: Returns the current session language.

Default Type Formula You can enter Excel-compatible formulas as default values for fields. Follow the Excel formula syntax and enclose field names in brackets.

For example: [credit]+[debit]

Note that referencing the field names rather than the cell names prevents your formulas from being corrupted if the order of the fields is changed in the layout.Document Properties

Protect Sheet - Select Yes or No to set the state of the document when downloaded. A protected sheet will allow you to update the data fields but will not allow you to insert rows. The user can change this setting in Excel by selecting Protection from the Tools menu.

Stylesheet - Select a stylesheet to apply to the document. Apply Filters - select Yes to enable Microsoft Excel filters for the lines region when the document is downloaded. The user can change this setting in Excel by selecting Filters from the Oracle menu. Data Span - enter the number of columns for the data to span.

Hide - select this box if you want the field hidden on the spreadsheet.

Read Only - select this box if you want the field to display as a non-updateable, read-only field.Context and Header Field Properties Prompt Span - Enter the number of columns that the field prompt will span.Important: For context and header fields, you set the number of columns for the Prompt, Hint, and Data to span. You set the column widths for the fields at the Line level. Therefore, when setting the column spans for a header or context field, be aware that the width of a column is determined by the width of the line fields in the spreadsheet.

Title - (optional) enter a title for the header. Hint Span - enter the number of columns for the field hint to span. The hint for a field can include the following: * - indicates the field is required. List - indicates that the field provides a list of values. Double-click the field to invoke the list.

Data type - the data type for each field is always displayed. For example, Text or Number

Line Region Properties

Data Entry Rows - enter the number of blank rows to display when the document is generated. The user can add more rows once the document is downloaded to Excel.

Width - enter the width of the field in characters.

Frozen Pane - use this selection to set the fields that you want to remain visible while you scroll horizontally across the spreadsheet.

Read OnlyA Step by Step Guide to Define Mapping

This example demonstrates how to define mapping between source data and columns in a spreadsheet.

1. Login to the application and navigate to Desktop Integrator -> Define Mapping2. Select Integrator for which you want to define mapping. Click on Go button.3. Select an existing mapping to update or create a new mapping by Click on Define mapping button.4. Enter Mapping Name, Mapping Key and Number of columns. Click on Next button.5. In the Define Mapping - Source to Target Columns window, associate columns being imported from the content to fields in the spreadsheet.6. Click the list of values for the Source Column to view a list of available columns to import, and then enter the search criteria. (If you know the name of the Source Column, you can type it directly into the field without using the list of values.) Click the radio button next to the column name, and then click select to select columns to map.7. Use the Target Column field next to each Source Column to create a mapping between the two fields. The Target Column list of values contains a list of columns that can exist in a spreadsheet. You may add new rows if more columns need to be mapped. Click the list of values for the Target Column to view a list of available columns to import, and then enter the search criteria. Click the radio button next to the column name, and then click select to select columns to map.8. Some Target Columns support the translation of ID values from Source Columns. To find out if the translation of IDs is supported by a specific column, select that column and click Lookup. If the column supports the ID translation, a check box appears under Lookup for that column name. To perform the ID translation, select the Lookup check box for the desired columns.9. Apply the mapping definition you have created.Setting Up Form Functions, Menus, and ResponsibilitiesThis example demonstrates how to call a WEB ADI from a responsibility menu.1. Login to the application and navigate to System Administrator -> Application -> Function.

2. Create a new function using the following details

Function - Enter a unique function name

User Function Name - Enter the function name

Type - SSWA servlet function

Parameter - bne:page=BneCreateDoc&

bne:viewer=BNE:EXCEL2007&

bne:reporting=(Y orN depend upon your integrator type)&

bne:integrator=APPLICATION_SHORT_NAME:INTEGRATOR_CODE& bne:layout=APPLICATION_SHORT_NAME:LAYOUT_CODE& bne:content=APPLICATION_SHORT_NAME:CONTENT_CODE& bne:rows=(FLAGGED or ALL)& bne:validation=(Y or N)& bne:import=Y& bne:importFlex=NOIMPORT

Web HTML - BneApplicationService

3. Login to the application and navigate to System Administrator -> Application -> Menu4. Query for a menu of a responsibility and add this function to the menu.5. Go to the responsibility and run click on this menu.LOV to an Integrator

This example demonstrates how to create a LOV on an integrator field.

Call the procedure BNE_INTEGRATOR_UTILS.CREATE_TABLE_LOV using below parameters.

Like you want to create a LOV on DEPTNO column using query- SELECT DEPTNO, DNAME FROM DEPT;

P_APPLICATION_ID Integrator Application ID

P_INTERFACE_CODE Interface Code

P_INTERFACE_COL_NAME On which column of Interface you want to create LOV

P_ID_COL Column of LOV Query (DEPTNO)

P_MEAN_COL Column of LOV Query (DNAME)

P_DESC_COL NULL if there is no Description

P_TABLE Table of LOV Query (DEPT)

P_ADDL_W_C 1=1, If no additional where clause

P_WINDOW_CAPTION NULL (Optional)

P_WINDOW_WIDTH 400 (Popup window width)

P_WINDOW_HEIGHT 300 (Popup window height)

P_TABLE_BLOCK_SIZE 10 (No of records in each block)

P_TABLE_SORT_ORDER NULL (Optional)

P_USER_ID Use ID (Created By)Technical Information

Integrator BNE_INTEGRATORS_B

BNE_INTEGRATORS_TL

BNE_INTEGRATORS_VLLayout BNE_LAYOUTS_B

BNE_LAYOUTS_TL

BNE_LAYOUTS_VLLayout Columns BNE_LAYOUT_COLS

BNE_LAYOUT_COLS_VMapping BNE_MAPPINGS_B

BNE_MAPPINGS_TL

BNE_MAPPINGS_VL

Content BNE_CONTENTS_B

BNE_CONTENTS_TL

BNE_CONTENTS_VL

InterfaceBNE_INTERFACES_B

BNE_INTERFACES_TL

BNE_INTERFACES_VL

Sql Qury to get Package and View name used in IntegratorSELECT BIT.USER_NAME WEB_ADI, BA.ATTRIBUTE2 "PACKAGE", BCT.USER_NAME "VIEW"

FROM BNE_INTEGRATORS_TL BIT,

BNE_ATTRIBUTES BA,

BNE_CONTENTS_TL BCT

WHERE substr(BIT.INTEGRATOR_CODE,1,length(BIT.INTEGRATOR_CODE)-5)||'_P0_ATT' = BA.ATTRIBUTE_CODE

AND BIT.APPLICATION_ID = BCT.APPLICATION_ID

AND BIT.LANGUAGE = 'US'

AND BCT.LANGUAGE = 'US'

AND BA.ATTRIBUTE1 = 'PROCEDURE'

AND BIT.APPLICATION_ID = BA.APPLICATION_ID

AND BCT.CONTENT_CODE = substr(BIT.INTEGRATOR_CODE,1,length(BIT.INTEGRATOR_CODE)-5)||'_CNT'

AND BIT.USER_NAME LIKE 'XX Test Create'

order by BIT.USER_NAME;

FNDLOAD command for WEB ADI

Integrator FNDLOAD apps/$APPS_PASSWORD 0 Y DOWNLOAD $BNE_TOP/admin/import/bneint.lct

GENERAL_223_INTG.ldt BNE_INTEGRATORS INTEGRATOR_ASN=XXCUST

INTEGRATOR_CODE="GENERAL_223_INTG

FNDLOAD apps/$APPS_PASSWORD 0 Y UPLOAD $BNE_TOP/admin/import/bneint.lct

GENERAL_223_INTG.ldtLayout FNDLOAD apps/$APPS_PASSWORD 0 Y DOWNLOAD $BNE_TOP/admin/import/bnelay.lct

XX_TEST_CREATE_LAYOUT.ldt BNE_LAYOUTS LAYOUT_ASN=XXCUST

LAYOUT_CODE=" XX_TEST_CREATE_LAYOUT

FNDLOAD apps/$APPS_PASSWORD 0 Y UPLOAD $BNE_TOP/admin/import/bnelay.lct

XX_TEST_CREATE_LAYOUT.ldt

Mapping FNDLOAD apps/$APPS_PASSWORD 0 Y DOWNLOAD $BNE_TOP/admin/import/bnemap.lct

XX_HR_86_MAP.ldt BNE_MAPPINGS MAPPING_ASN="PER" MAPPING_CODE="HR_86_MAP

FNDLOAD apps/$APPS_PASSWORD 0 Y UPLOAD $BNE_TOP/admin/import/bnemap.lct

XX_HR_86_MAP.ldt

Content FNDLOAD apps/$APPS_PASSWORD 0 Y DOWNLOAD $BNE_TOP/admin/import/bnecont.lct

GENERAL_223_CNT.ldt BNE_CONTENTS CONTENT_ASN=XXCUST

CONTENT_CODE=" GENERAL_223_CNT

FNDLOAD apps/$APPS_PASSWORD 0 Y UPLOAD $BNE_TOP/admin/import/bnecont.lct

GENERAL_223_CNT.ldt

Appendices

Appendix A Authors

(List of the primary author(s) and contributors)

Appendix B References

(Metalink Note ID : 360105.1)