Implementing Oracle Web Applications Desktop Integrator

This appendix covers the following topics:

Overview

This appendix describes how to implement Oracle Web Applications Desktop Integrator. It applies to all integrators that use the Create Document interface. It describes how to set profile options to control specific Oracle Web Applications Desktop Integrator functions, as well as how to set up functions to call the Oracle Web Applications Desktop Integrator Create Document interface and grant them to users. Once set up, a user can create a spreadsheet to download and upload data to a specific product. Use this appendix in conjunction with the product-specific documentation.

This appendix also lists diagnostic tests you can use to check the setup of Oracle Web Applications Desktop Integrator and review troubleshooting information.

Optional Action: You can use themes to customize the look and feel of Oracle Web Applications Desktop Integrator pages. Themes are reflected in all Oracle Web Applications Desktop Integrator pages regardless of their underlying technology. See: Themes, Oracle Application Framework Personalization Guide.

Setting Profile Options

The following profile options can be set to control specific Oracle Web Applications Desktop Integrator functions in your system. For more information on profile options, see: Overview of Setting User Profiles, Oracle E-Business Suite Setup Guide.

For information about the FND: Enable BNE Table Integration profile option, see Oracle Application Framework Profile Options in the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.

BNE Allow No Security Rule

A production instance of Oracle E-Business Suite should have this profile option set to No.

The default value is No.

BNE Allow Set Parameters

Valid values are Yes and No. If this profile option is set to No, users will not be able to access the upload parameters window.

BNE Disable

Valid values are Yes and No. If set to Yes, all Oracle Web Applications Desktop Integrator functionality is disabled. This can be set at the Site, Application, Responsibility and User level. You can use this option to restrict access to Oracle Web Applications Desktop Integrator functionality at levels where you do not plan to allow use of integrators.

BNE Document Lifetime

Spreadsheets created by Oracle Web Applications Desktop Integrator can be saved, opened, and used again at a later date to interact with Oracle E-Business Suite. Use this option to disable a spreadsheet from connecting to the database after a specific length of time from the creation date. Select from a range of hours, days, months, or years.

BNE Enable Digital Signature

Use this profile option to enable Oracle Web Applications Desktop Integrator to affix a digital signature to the spreadsheets you create, identifying them as coming from a trusted source. You can then select a macro security level in Microsoft Excel that requires digital signatures when working with these spreadsheets. See: Selecting Macro Security Settings in Microsoft Excel.

The default value is No.

Note: Oracle Report Manager uses the Oracle Web Applications Desktop Integrator integration with Microsoft Excel to generate spreadsheets for the Financial Report Template Editor and for the Microsoft Excel output for Financial Statement Generator reports. Consequently, if you use these Oracle Report Manager features, then this profile option also controls the use of digital signatures for those spreadsheets. For more information, see: Setup Overview, Oracle Report Manager User's Guide.

BNE: Enable OOXML Standard

Set this profile option to Yes to enable Oracle Web Applications Desktop Integrator to create spreadsheets according to the Office Open XML (OOXML) standard. When using the OOXML format, Oracle Web Applications Desktop Integrator performs the processing for document creation and upload on the Oracle E-Business Suite server rather than on the desktop. With this option, no macros are used during document creation and limited macros are used during upload. Consequently, the Trust access to the VBA project object model security option is not required to work with OOXML documents. Also, because the processing is performed on the server, document creation and upload use minimal desktop resources. See: Using the Office Open XML Format.

The default value is Yes.

Note: This profile option does not apply to spreadsheets exported from tables in Oracle Application Framework pages. Such spreadsheets are always created as OOXML documents, regardless of the setting specified in this profile option.

BNE: Enable Simplified Create Document

By default, Oracle Web Applications Desktop Integrator displays the Create Document interface as a single page in which users can enter all the document parameters. To display the Create Document page flow, which guides users through multiple pages to enter the document parameters, set this profile option to No.

The default value is Yes.

BNE: Enable Simplified Define Layout

By default, Oracle Web Applications Desktop Integrator displays the Define Layout interface as the Define Layout page flow, which guides users through multiple pages to enter the layout properties. To display the Define Layout page, which lets users enter all the layout properties in a single page after selecting the integrator to which the layout applies, set this profile option to Yes.

The default value is No.

BNE: Enable Simplified Define Mapping

By default, Oracle Web Applications Desktop Integrator displays the Define Mapping interface as the Define Mapping page flow, which guides users through multiple pages to enter the mapping properties. To display the Define Mapping page, which lets users enter all the mapping properties in a single page after selecting the integrator to which the mapping applies, set this profile option to Yes.

The default value is No.

BNE: Enable Upload Compression

If your site does not use OOXML, set this profile option to Yes to enable Oracle Web Applications Desktop Integrator to compress the data that you upload from a spreadsheet to Oracle E-Business Suite. Compression increases the number of records that you can upload at once. You can use either WinZip or 7Zip as the compression application. See: Compressing Data for Upload.

The default value is No.

Note: If your site uses OOXML, then the spreadsheet is automatically uploaded as a ZIP compressed OOXML file.

BNE Enforce Parameter Values

If a required parameter is invalid or is not sent by the function calling the Oracle Web Applications Desktop Integrator service, the user will be shown a page to enter the required parameter so the create document process can be completed. If this profile option is set to Yes, users will not be able to enter parameter values and will be shown an error stating that they should have their system administrator edit the function to correct the problem.

BNE Excel Worksheet Maximum

If your site does not use OOXML, use this profile option to set the maximum number of worksheets that Oracle Web Applications Desktop Integrator can create within a workbook. This is unlimited by default.

Note: The number of worksheets that can be added to a spreadsheet is limited only by the available memory resources. Setting this option allows you to manage your memory resources and avoid potential crashes for users working on older, less resource-rich clients.

If your site uses OOXML, then this profile option is not applicable because the document is processed on the server rather than on the client.

BNE Offline List of Values Limit

This profile option specifies the maximum number of values to download and display in the list of values for fields based on a value set and for a dependent segment. If there are more possible values than the maximum you set here, the spreadsheet displays only the first values in the list, up to the specified limit.

BNE Server Log Filename (also known as BNE Debug Log Filename)

Use this profile option to change the name of the Oracle Web Applications Desktop Integrator log file on the middle tier. If this profile option is not set, bne.log is used.

The default value is bne.log. You should set this profile option only at site level.

BNE Server Log Level (also known as BNE Debug Log Level)

This profile option determines the level of detail that is recorded in the Oracle Web Applications Desktop Integrator log file. The valid values are listed below. The level of granularity and amount of information recorded to the log file increases as you move down the list.

The default value is ERROR. You should set this profile option only at site level.

BNE Server Log Path (also known as BNE Debug Log Directory)

This profile option can be used to set the directory for the Oracle Web Applications Desktop Integrator log file on the application server. This directory must be in the non-editioned file system. If this profile option is not set, then the FND_TOP/log directory is used.

The default value is FND_TOP/log. You should set this profile option only at site level.

For more information about the non-editioned file system, see: File System Structure, Oracle E-Business Suite Concepts.

BNE Upload Batch Size

All of the rows in the spreadsheet are uploaded from the client machine to the middle tier at once; the Upload Batch Size determines the number of records sent to the database at one time from the middle tier. The default is 100. System administrators can adjust this setting to find the batch size that optimizes upload time for their environment. This setting should not be less than 5 or greater than 200. Network packet sizes, latency and average number of rows uploaded from the client affect the optimal setting of this value. If there is a large distance between the middle tier and the database, you may want to increase the batch size to reduce the number of trips over the network. You also want to make sure that the amount of data sent in a batch takes full advantage of the size of packets on your network using the average number of rows users will be uploading. You should set this profile option only at site level.

BNE Upload Retry Count

This profile option specifies how many times Oracle Web Applications Desktop Integrator should check the concurrent request status for an upload. This profile option applies only for synchronous imports. If the concurrent request has not completed after the maximum number of checks has been reached, then the upload fails.

The default value is 50. You should set this profile option only at site level.

BNE Upload Sleep Seconds

This profile option specifies the number of seconds to sleep after checking the concurrent request status for an upload before checking again.

The default value is 3. You should set this profile option only at site level.

BNE Upload Staging Directory

This profile option specifies the file system directory where uploaded data is initially stored as an XML stream file. This directory must be a shared directory within the non-editioned file system.

The default value is BNE_TOP/upload. You should set this profile option only at site level.

For more information about the non-editioned file system, see: File System Structure, Oracle E-Business Suite Concepts.

BNE Upload Text Directory

This profile option specifies the file system directory to use when a document is created that is initially populated with data from a text file. The content file is temporarily stored in this directory as an XML file. This directory must be in the non-editioned file system.

The default value is BNE_TOP/upload. You should set this profile option only at site level.

For more information about the non-editioned file system, see: File System Structure, Oracle E-Business Suite Concepts.

BNE Viewer Displays Image

Set this profile option to null or Yes to include a branding image in your Oracle Web Applications Desktop Integrator spreadsheets. You can specify an image at the layout level, at the style sheet level, or through the Corporate Branding Image for Oracle Applications profile option. If you do not want to display an image in your spreadsheets, set the BNE Viewer Displays Image profile option to No. See: Implementing Branding Images.

BNE XML Response Compression

If set to null or Yes, XML compression is used when downloading data to the spreadsheet. Some browsers do not support this XML compression, so you may need to set this option to No for some users to avoid errors.

Additional Profile Options

The following profile options are for internal use within Oracle Web Applications Desktop Integrator only. Do not change the settings for these profile options from the default values.

The following profile options are no longer used. Do not change the settings for these profile options from the default values, except where noted.

Setting Up Functions, Menus, and Responsibilities

Oracle Web Applications Desktop Integrator provides seeded functions and a seeded menu and responsibility for its functionality. You can assign the seeded responsibility to users who should have access to all the functionality it includes. You can also add the seeded functions to your own menus and responsibilities to provide your users access to specific functionality as needed. Additionally, you can create your own functions that enable users to create specific Oracle Web Applications Desktop Integrator documents. You can then add your custom functions to the menus and responsibilities you choose.

Oracle E-Business Suite products that use integrators may also include access to Oracle Web Applications Desktop Integrator functionality in their own menus or functional page flows. Consult your product documentation for information on accessing these functions.

Note: Integrators are not installed with Oracle Web Applications Desktop Integrator, but with their associated products.

The seeded functions are used to secure the associated functionality. Even if you provide alternate navigation through a separate menu item or page flow, you must also add the relevant seeded function to a responsibility assigned to a user in order for the user to work with that functionality. For example, a user must have a responsibility that includes the BNE_ADI_CREATE_DOCUMENT function in order to create Oracle Web Applications Desktop Integrator documents, even if you give that user access to the Create Document interface through a custom function. In this case the seeded BNE_ADI_CREATE_DOCUMENT function does not need to be displayed to the user in the menu.

Additionally, access to specific integrators is secured by the functions defined as security rules for each integrator. You must add at least one of the functions for an integrator to a responsibility assigned to a user in order for the user to work with that integrator.

Seeded Functions

The following table describes the functions that are automatically created.

Seeded Functions
Function Description
BNE_ADI_CREATE_DOCUMENT Allows users to access the Create Document interface. This interface prompts users for parameters that determine how a formatted spreadsheet is generated on the desktop.
BNE_ADI_DEFINE_LAYOUT Allows users access to the user interface to define layouts. Users are prompted to select a layout in the Create Document interface. The layout determines the fields that are included in the spreadsheet, their placement, and whether they have default values.
BNE_ADI_DEFINE_MAPPING Allows users to access the interface to define mappings. Mappings are used to import information into a spreadsheet. Users can select a content in the Create Document interface to import information from a text file or from Oracle E-Business Suite tables into a spreadsheet. The mapping associates data in the content with fields in the spreadsheet.
BNE_ADI_DEFINE_STYLESHEET Allows users access to the define style sheet user interface. The style sheet sets the colors and font styles used in the spreadsheet.
BNE_ADI_LOB_MANAGEMENT Specific to the Human Resources application. You do not need to give users access to this function unless they use mail merge functionality in Oracle HRMS. See My Oracle Support Knowledge Document 394265.1 for more information on HRMS functionality.
BNE_ADI_SETUP_OPTIONS Allows system administrators to define right-justification and zero-fill format masking for key flexfields. This setting will override the flexfield value set definition.

Seeded Menu

The Desktop Integration Menu is created with the following prompts:

Seeded Responsibility

The Desktop Integration responsibility is created with the Desktop Integration Menu.

Granting Users the Ability to Create Documents

The sections that follow apply to integrators that are accessed through the Create Document interface.

Creating Functions Using the Create Document Interface

You can go through the Create Document interface and select all parameters, then save the parameters to a function.

Follow these steps to create a function with specified parameter values. If your site uses the single Create Document page, then parameters with values specified in the function appear as read-only fields. If your site uses the Create Document page flow with multiple pages and a page in the flow is to be skipped, every parameter on that page must be specified in the function.

Specifying Skipped Parameters

  1. Log in to Oracle E-Business Suite as a user with access to the relevant integrator and select the Create Document function.

  2. Enter the parameter values you want to save in the Create Document interface.

  3. Click Save in the Create Document page or in the Review page of the page flow. The Shortcut popup window or Select Shortcut window opens, respectively.

  4. Enter a name for your function in the Shortcut Name field. This name will have the prefix BNE_ when you search for it in Oracle E-Business Suite.

  5. Select Save to Form Function.

  6. Select the parameters you want to save to the function and determine if the Create Document page or the Review page will be displayed.

    If all the parameters are saved and you choose not to display a page to let the users review those parameters, then the document will immediately be created when the user selects the function. If you do not save some of the parameters, then users must manually specify those parameters in the Create Document interface before they can create the document.

    Note: The Viewer and Reporting parameters must be saved if you do not want them to be displayed for users to enter a value. If you have users with different versions of Excel creating documents for upload in English, you may want to create separate functions; one for each viewer.

  7. Log in to Oracle Forms with the System Administrator responsibility and attach the function to a menu. Under Application, select Menu, and search for BNE_<name entered in Step 4>. You must attach the function to the same menu that contains the security function that grants access to the integrator. You must also include the BNE_ADI_CREATE_DOCUMENT function, although this function does not need to be displayed to the user.

Creating and Editing Functions in Oracle Forms

System administrators can create functions using these steps for integrators that are used through the Create Document interface. See your product documentation for the security function that must be placed in the same menu structure for access to the integrator.

To create your own functions:

Note: You must also include the corresponding seeded function in the menu structure for access to the Oracle Web Applications Desktop Integrator functionality, although this function does not need to be displayed to the user.

Including Parameter Values in the Create Document Function

When users create documents they are prompted for a number of parameters that determine how their spreadsheet will be created. These parameters can be specified within the function to secure parameter values and force users to use certain values. When users access the single Create Document page, parameters with values specified in the function appear as read-only fields. When users access the Create Document page flow, pages prompting users for values specified in the function will not be displayed; this reduces the number of steps they must take to create documents.

The table that follows provides a description of each parameter that determines page flows.

Parameters for Create Document Interface
Page in the Create Document Page Flow Parameter Required/Optional Description
Viewer Bne:viewer Required The desktop program that will be used to view the spreadsheet.
Viewer Bne:reporting Required If selected, the spreadsheet created will not allow upload of data.
Integrator Bne:integrator Required Indicates that the Oracle E-Business Suite task users will be using the desktop.
Layout Bne:layout Required The Layout determines the fields in the spreadsheet, their placement, and their default values. Valid values depend on the integrator you select.
Content Bne:content Optional Points to information that will be imported into the spreadsheet. Valid values depend on the integrator you select.
Map Bne:map Required, if Content is chosen Provides the relationship between data in the content and fields in the spreadsheet. Valid values depend on the integrator you select.

Providing Users a Secured List of Values

You might want to grant access to several parameter values. Hard coding these parameter values in the function would require you to create a Self-Service link for every parameter you wish to grant to a user. You can work around this by allowing users to choose from a restricted list of parameter values.

For example, twenty layouts may be defined for an integrator; however, you can create a function that will allow users to see only ten. You can do this by defining more than one value for the bne:layout parameter in the function definition.

  1. Log in to Oracle E-Business Suite with the System Administrator responsibility.

  2. Navigate to the Form Functions window and look up a function that calls the Create Document interface.

  3. Go to the Parameter field and locate the parameter you want to secure and add a comma-separated list of valid values, or a partial value that includes a wild card that will return more than one parameter value.

    Parameter values can be referenced by their internal key names or by their user visible values.

    The sections that follow discuss how to enter internal keys, enter user values, and use wild cards.

Entering Internal Keys

  1. Parameter values are saved in the format of the Application Short Name:Key; For example, bne:integrator=

    BNE:JOURNALS_120&bne:layout = BNE:FUNCT_ACT_SINGLE_120.

    To give the user two options for a layout, you would enter bne:layout=

    BNE:FUNCT_ACT_SINGLE_120,BNE:FUNCT_ACT_MULTIPLE_120.

  2. If you are only using the Journals integrator, all of your parameter values will be using the BNE application short name.

    To ensure that you have entered a valid value for a parameter, go through the Create Document interface, select the layout you want to grant to users, and choose Save to create a function after completing the Create Document page or in the Review page. Then log in as System Administrator, look up the function and note the key that was saved for the layout.

Entering User Values

If you do not know the key value for a layout, your function can reference the name of the layout that appears in the Create Document interface.

  1. Navigate to the layout parameter in the Create Document interface and choose the layouts you want the user to access. For example, you might choose the layouts "Functional Actuals - Single" and "Functional Actuals - Multiple".

  2. Log in as System Administrator and look up the function.

  3. Go to the parameter field and enter a comma separated list of the layout names using the following format:

    parameter name=USER_NAME:user name,USER_NAME:user name

    In this example, you would enter: "bne:layout=USER_NAME:Functional Actuals - Single, USER_NAME:Functional Actuals - Multiple".

    Note: The user name you enter in the function must match the names you see in the Create Document interface.

Using Wild Cards

You can create restricted lists by entering a value for the bne:layout parameter that includes a wild card (%). The wild card character (%) must be escaped with "25". In this example, you would enter bne:layout=USER_NAME:Fu%25 to restrict the list to "Functional Actuals - Single" and "Functional Actuals - Multiple". These will be the layouts shown to the user because they are the only layouts whose names begin with "Fu".

Running Diagnostic Tests

Oracle Diagnostics Framework provides a mechanism which makes Oracle E-Business Suite more supportable and robust by providing predefined tests to check for key setup requirements. Oracle Web Applications Desktop Integrator provides tests through Oracle Diagnostics Framework that you can use to check the setup of Oracle Web Applications Desktop Integrator and review troubleshooting information. These tests are available in Oracle Diagnostics Framework under the Web Applications Desktop Integrator application. For information on running tests in Oracle Diagnostics Framework, see: Oracle Diagnostics Framework User's Guide.

WebADI Diagnostics

The following tests are available in the WebADI Diagnostics group.

WebADI Module Versions and Profile Values

This test reports details about the versions of Oracle Web Applications Desktop Integrator and its components installed in your Oracle E-Business Suite instance, and about the values set for Oracle Web Applications Desktop Integrator profile options. You can use this information to verify your implementation or to help diagnose any errors.

Select the responsibility ID to use when running this test.

The report displays release or patch version and selected configuration details for the following:

For each Oracle Web Applications Desktop Integrator profile option, the report shows the current value and default value, and indicates whether the source of the current value is an Oracle seeded setting or a custom setting entered in your instance. For profile options that can be set at the responsibility and user level, the report shows the value for the responsibility you selected or for your user ID, as appropriate.

Next, the report displays version details for Oracle Web Applications Desktop Integrator Java classes under the oracle.apps.bne hierarchy, PL/SQL packages, and servlets. The report also provides information about any invalid database objects for Oracle Web Applications Desktop Integrator.

Finally, the report provides links to related My Oracle Support Knowledge Documents, and XML file details for the WebADI Module Versions and Profile Values test itself.

WebADI Integrator Metadata

This test reports details about the metadata defined for a particular integrator. You can use this information to verify the integrator definition or to help diagnose any errors.

Select the responsibility ID and the integrator for which you want to run this test.

The report displays release or patch version and selected configuration details for the following:

Next, the report displays the various types of metadata that make up the integrator definition. Choose the See SQL links to view the SQL queries used to retrieve the metadata. The report includes the following:

Finally, the report provides a key to some abbreviations used in the metadata details, links to related My Oracle Support Knowledge Documents, and XML file details for the WebADI Integrator Metadata test itself.

For more information about defining integrators and how each type of metadata is used, see Defining Integrators, Oracle E-Business Suite Desktop Integration Framework Developer's Guide, Defining Layouts, and Defining Mappings.