This appendix covers the following topics:
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.
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.
A production instance of Oracle E-Business Suite should have this profile option set to No.
The default value is No.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Use this profile option to change the name of the Oracle Web Applications Desktop Integrator log file on the application 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.
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.
CRITICAL_ERROR - Messages that are the result of a system failure. The integrity and reliability of the system is in doubt as a result of this error.
ERROR - Messages that are the result of an unexpected error in the system. It is possible to recover from these errors; the system may still be in a usable state. Setting the profile option to this value will include CRITICAL_ERROR messages in the log file. This is the default setting and the recommended value for a production environment.
WARNING - Messages trapped by the application. These errors were handled by the application but the system administrator should be aware of them occurring. Setting the profile option to this value will include ERROR as well.
INFORMATION - Additional messaging is added to the log file that includes processing information. Setting the profile option to this value includes CRITICAL_ERROR, WARNING, and ERROR log messages.
DETAIL - Messages that summarize what is written to the log file. Setting the profile option to this value includes CRITICAL_ERROR, WARNING, ERROR, and INFORMATION log messages.
TRACE - Messages that provide detailed debugging information. Setting the profile option to this value includes CRITICAL_ERROR, WARNING, ERROR, INFORMATION, and DETAIL log messages.
Additionally, if you select the value TRACE, then Oracle Web Applications Desktop Integrator displays the name of the Java module that renders the current page in the lower left corner of the page. Furthermore, if you select TRACE, then Oracle Web Applications Desktop Integrator displays the WebADI.xls file while it is being generated and does not delete it.
Note: Similarly, if you use Oracle Report Manager and you select TRACE for this profile option, then Oracle Report Manager displays the ReportManager.xls file while it is being generated for the Financial Report Template Editor and for the Microsoft Excel output for Financial Statement Generator reports, and does not delete it.
The default value is ERROR. You should set this profile option only at site level.
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.
All of the rows in the spreadsheet are uploaded from the client machine to the application tier at once; the Upload Batch Size determines the number of records sent to the database at one time from the application 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 application 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.
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.
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.
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.
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.
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.
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.
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.
BNE Redirect Home Enabled
BNE Redirect Portal URL
BNE Servlet Path
BNE UIX Headless Mode Enabled
The following profile options are no longer used. Do not change the settings for these profile options from the default values, except where noted.
BNE FND Jar Path
BNE JAR Path
BNE Servlet Link
BNE UIX Base Path
BNE UIX Physical Directory
Note: You should delete any value stored in this profile option.
BNE Upload Import Directory
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.
The following table describes the functions that are automatically created.
| 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. |
The Desktop Integration Menu is created with the following prompts:
Create Document (BNE_ADI_ CREATE_DOCUMENT)
Define Layout (BNE_ADI_DEFINE_LAYOUT)
Define Mapping (BNE_ADI_DEFINE_MAPPING)
Manage Document Links (BNE_ADI_LOB_MANAGEMENT)
Setup Options (BNE_ADI_SETUP_OPTIONS)
Define Style Sheet (BNE_ADI_DEFINE_STYLESHEET)
The Desktop Integration responsibility is created with the Desktop Integration Menu.
The sections that follow apply to integrators that are accessed through 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
Log in to Oracle E-Business Suite as a user with access to the relevant integrator and select the Create Document function.
Enter the parameter values you want to save in the Create Document interface.
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.
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.
Select Save to Form Function.
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.
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.
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:
Set the Type to SSWA SERVLET FUNCTION for all Oracle Web Applications Desktop Integrator functions
Set the HTML Call for all Oracle Web Applications Desktop Integrator functions to BneApplicationService
To create a function allowing users to create documents, set the parameter field to bne:page=BneCreateDoc
To create a function allowing users to define layouts, set the parameter field to bne:page=BneDefineLayout
To create a function allowing users to define mappings, set the parameter field to bne:page=BneMappingTemplate
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.
Create Document: BNE_ADI_ CREATE_DOCUMENT
Define Layout: BNE_ADI_DEFINE_LAYOUT
Define Mapping: BNE_ADI_DEFINE_MAPPING
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.
| 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. |
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.
Log in to Oracle E-Business Suite with the System Administrator responsibility.
Navigate to the Form Functions window and look up a function that calls the Create Document interface.
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.
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.
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.
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.
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".
Log in as System Administrator and look up the function.
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.
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".
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.
The following tests are available in the WebADI Diagnostics group.
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:
The Oracle Database used by your Oracle E-Business Suite instance
The Web Applications Desktop Integrator application
Oracle E-Business Suite Diagnostics
The Application Object Library application
The XML Publisher application
The Oracle E-Business Suite Applications Technology product family (ATG_PF)
Oracle E-Business Suite
JDK
JDBC
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.
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:
The Oracle Database used by your Oracle E-Business Suite instance
The Web Applications Desktop Integrator application
Oracle E-Business Suite Diagnostics
The Application Object Library application
The XML Publisher application
The Oracle E-Business Suite Applications Technology product family (ATG_PF)
Oracle E-Business Suite
JDK
JDBC
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:
The overall integrator definition, including basic integrator properties, parameter lists used by the integrator, and security rules defined for the integrator
Note: For each security rule, the report shows whether the responsibility for which you ran this test is allowed or denied access to the securing function.
The report displays a warning if the integrator is either not enabled or not displayed in the Create Document interface. For information about enabling an integrator or changing the display setting, see: Defining Integrators, Oracle E-Business Suite Desktop Integration Framework Developer's Guide.
Any interfaces defined for the integrator, including interface attributes, user interface display details for those attributes, any list of values components assigned to interface attributes, any attribute groups, and any list of values components assigned to attribute groups
Any contents defined for the integrator, including content columns and any parameter list defined for the content
The uploader defined for the integrator, if any, and the uploader parameters
The importer defined for the integrator, if any, including the importer rules that define the steps performed by the importer, and the parameters for the importer rules
The layouts defined for the integrator, including the layout blocks and layout columns
Any mappings defined for the integrator, including the interface and the content being mapped and the mapping lines that link the interface attributes with content columns
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.