Oracle® Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1.5.0) E10139-04 |
|
![]() Previous |
![]() Next |
This appendix provides guidelines on how you can troubleshoot an integrated Excel workbook when you encounter problems during development. It also describes possible solutions for a number of problems that you may encounter.
This appendix includes the following sections:
Section C.1, "Verifying That Your Fusion Web Application Supports ADF Desktop Integration"
Section C.2, "Verifying End-User Authentication for Integrated Excel Workbooks"
Section C.3, "Generating Log Files for an Integrated Excel Workbook"
Note: The property inspector does not validate that values you enter for a property or combinations of properties are valid. Invalid values may cause runtime errors. To avoid runtime errors, make sure you specify valid values for properties in the property inspector. For more information about the property inspector, see Section 5.6, "Using the Property Inspector." |
Using a specific URL, you can verify that the Fusion web application is running the ADF Desktop Integration remote servlet (adfdiRemote
), and the version of ADF Desktop Integration. This information can be useful if you encounter errors with an integrated Excel workbook. For example, you can determine whether the ADF Desktop Integration remote servlet is running when you are troubleshooting an integrated Excel workbook.
To verify that the ADF Desktop Integration remote servlet is running:
Log on to the Fusion web application.
Type the concatenated values of the workbook properties WebAppRoot
and RemoteServletPath
into the address bar of your web browser. This corresponds to a URL similar to the following:
http://hostname:7101/FusionApp/adfdiRemoteServlet
If the ADF Desktop Integration remote servlet is running, a web page returns displaying a message similar to the following:
ADF Desktop Integration Remote Servlet 11g (11.1.1.48.86) [520] Response from oracle.adf.desktopintegration.servlet.DIRemoteServlet: OK.
If end users of an integrated Excel workbook do not get prompted for user credentials when they invoke an action that interacts with the Fusion web application configured with ADF security, it may mean that security is not configured correctly for either the integrated Excel workbook or the Fusion web application. You can verify that your secure Fusion web application authenticates end users and that it is security-enabled by carrying out the following procedure.
To verify that a secure Fusion web application authenticates end users:
Enter the value of the workbook properties WebAppRoot
into the address bar of your web browser. This corresponds to a URL similar to the following:
http://hostname:7101/FusionApp/adfdiRemoteServlet
If the Fusion web application is security-enabled, it will request that you enter user credentials.
For more information about securing your integrated Excel workbook, see Chapter 11, "Securing Your Integrated Excel Workbook."
ADF Desktop Integration can generate log files that capture information based on events triggered by the following pieces of software within ADF Desktop Integration:
HTTP filter and the ADF Desktop Integration remote servlet on the web server (server-side logging)
For more information about server-side logging, see Section C.3.1, "About Server-Side Logging."
Excel workbook which you integrate with your Fusion web application (client-side logging)
For more information about client-side logging, see Section C.3.2, "About Client-Side Logging."
You configure the generation of server-side log files for ADF Desktop Integration the same way as for other Oracle ADF modules. This involves setting values that specify the verbosity level and output location in a configuration file named j2ee-logging.xml
. You can also use Oracle Diagnostic Logging Configuration of JDeveloper to configure the logging levels specified in the logging.xml
file. For more information about using the JDeveloper debugging tools and ADF Logger, see the "Using the ADF Logger" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Table C-1 describes the package names that you supply as attribute parameters to the <logger>
elements in the j2ee-logging.xml
file to configure log file generation in ADF Desktop Integration.
Table C-1 Package Names for Log File Configuration
To generate log file entries for this component... | Enter this package name... |
---|---|
All ADF Desktop Integration server logic |
|
ADF Desktop Integration remote servlet |
|
ADF Desktop Integration HTTP filter |
|
Table C-2 describes the types of information that the log file captures and the corresponding log file entry level.
Table C-2 Server-Side Logging Levels
Log Level | Description |
---|---|
|
Captures all exceptions and errors. |
|
Captures all irrecoverable problem conditions. |
|
Captures lifecycle events such as servlet initialization, and so on. |
|
Captures "heartbeat" events that echo status and execution context for each client-server interaction. |
|
These values generate increasing levels of diagnostic information. |
You can configure ADF Desktop Integration to save logs of triggered events on the client. By default, no log files are generated. For more information about how to configure the Oracle ADF Desktop Integration module to save logs, see Section C.3.2.1, "How to Configure ADF Desktop Integration to Save Logs.".
ADF Desktop Integration provides logging tools to generate event logs and make them easily accessible. The logging tools are located in the Logging group of the Oracle ADF tab, and are available in both the design mode and the test mode.
Figure C-1 shows the logging tools in the Oracle ADF tab.
The Logging group provides the following buttons:
Console
Displays the ADFdi Logging Console window, which enables you to review the recent log entries while you are developing and testing the integrated Excel workbook. The console displays entries that are logged while the console is open. Figure C-2 illustrates the ADFdi Logging Console window with information and error log entries.
The console is a resizable, non-modal window with a buffer size of 64,000 characters. When the buffer is full, the old entries are removed. If you want to save log entries, you can copy them to a text file.
The dialog has the following buttons:
Set Level: Click to set the log output level. The button opens the Logging Output Level dialog, where you can choose the desired log output level.
Clear: Click to clear the log buffer.
Close: Click to close the dialog.
Note: A common ADFdi Logging Console window logs entries for all open integrated Excel workbooks. |
Set Output Level
Prompts you to choose the log output level. Table C-3 describes the log levels that client-side logging supports.
Table C-3 Client-Side Logging Levels
Level | Description |
---|---|
|
Captures critical information. |
|
Captures information about severe errors and exceptions. |
|
Captures irrecoverable conditions. |
|
Captures lifecycle and control flow events. |
|
Captures detailed information about the execution flow of the application. |
|
No logs are captured. This is the default value. |
Note: The log output level applies to all listeners for a given logger. |
Add Log Output File
Creates a new temporary logging listener to direct logging output to the specified file or format. In the Add New Temporary Logging Output File dialog, choose the desired file output type (text or XML), and specify the path and file name of the log output file.
The temporary listener directs the logging output for the current Excel session only, and is not registered in the ADF Desktop Integration configuration file. After you close the integrated Excel workbook, the temporary listener is removed.
Note: When you click the Add Log Output File button, a new listener is created. The new listener does not replace any existing listener defined in the ADF Desktop Integration configuration file, or any other temporary listener. |
Refresh Config
Reloads the ADF Desktop Integration configuration file. The ADF Desktop Integration configuration file determines the type of information logged by ADF Desktop Integration. It also determines the location and the output format of the log file.
For more information about the creation and configuration of the ADF Desktop Integration configuration file, see Section C.3.2.2, "About the ADF Desktop Integration Configuration File."
The ADF Desktop Integration configuration file is saved as adfdi-excel-addin.dll.config
in the Designer edition, and as adfdi-excel-addin-runtime.dll.config
in the Runtime edition. To determine the correct file name and location, click the About button in the Workbook group of the Oracle ADF tab. In the dialog that opens, click the Properties tab, and consult the Configuration entry for file name and location of configuration file.
For more information about elements of the configuration file, see the "Configuration File Schema for the .NET Framework" section in Microsoft Developer Network documentation. For more information about trace and debug settings, see the "Trace and Debug Settings Schema" section in Microsoft Developer Network documentation.
Example C-1 shows a sample configuration file, one of many valid ways to configure client-side logging, that generates two different log files with different formats (.txt
and .xml
). The file captures different types of information such as ThreadId
, ProcessId
, and DateTime
at a Verbose
logging level.
Example C-1 Sample Configuration File
<?xml version="1.0"?> <configuration> <system.diagnostics> <sources> <source name="adfdi-common" switchValue="Verbose"> <listeners> <add type="System.Diagnostics.DelimitedListTraceListener" name="adfdi-common-excel.txt" initializeData="c:\logs\adfdi-common-excel.txt" delimiter="|" traceOutputOptions="ThreadId, ProcessId, DateTime"/> <add type="System.Diagnostics.XmlWriterTraceListener" name="adfdi-common-excel.xml" initializeData="c:\logs\adfdi-common-excel.xml" traceOutputOptions="None"/> </listeners> </source> </sources> </system.diagnostics> </configuration>
Users who do not have access to the directory that stores the ADF Desktop Integration configuration file can change the location where log files are saved, and the logging level by setting values for user environment variables. You can add two user environment variables to configure the logging level and location for XML log files.
To add or configure user environment variables on Windows:
Click the Windows Start button and then click Settings > Control Panel.
In the Control Panel, double-click System.
In the System Properties dialog, click the Advanced tab, and then click the Environment Variables button.
In the Environment Variables dialog, click New under the User variables for username input field, and add variables as described in the following table.
Table C-4 User Enviroment Variables to Configure Logging
Enter a variable named... | With a value... |
---|---|
|
That defines the directory path and file name for the XML file that captures logging information. The directory that you specify here must exist before you add the |
|
That specifies the level of logging. Table C-3 lists valid values. |
Click OK.
The adfdi-common
object is an instance of the TraceSource
class from the System.Diagnostics
namespace in the Microsoft .NET Framework. This object is used to generate log files that capture information about events triggered by the Excel workbook that you integrate with your Fusion web application.
For more information about the TraceSource
class, see Microsoft Developer Network documentation.
You can export the XML metadata in your Excel workbook to an XML file with a name and location that you specify. This file may be useful if you have to debug or analyze an Excel workbook that is integrated with a Fusion web application. It contains child elements for each worksheet in the workbook, resources such as the relative path to the remote servlet, and so on.
The following procedure describes how you export XML metadata from an Excel workbook.
To export XML metadata from an integrated Excel workbook:
Click About in the Oracle ADF tab.
The About Oracle ADF 11g Desktop Integration dialog box appears.
Click the Properties view tab and then click the Export Metadata button.
A dialog box appears that asks you to specify a file name and location for the file that stores the exported metadata.
Specify a file name, a location, and then click Save.
The integrated Excel workbook exports the metadata to the specified file in the specified format.
This section describes the most common problems and their solutions.
SyncServletResponse
. Version x was found, version y was expected