|Oracle® Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)
Part Number E10139-02
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:
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.4, "Using the Property Inspector".
You can verify that your Fusion web application is running the Oracle ADF Desktop Integration remote servlet (
adfdiRemote) and the version that it runs. This information can be useful if you encounter errors with an integrated Excel workbook. For example, you can determine if the Oracle ADF Desktop Integration remote servlet is executing when troubleshooting an integrated Excel workbook.
To verify that the Oracle ADF Desktop Integration remote servlet is executing:
Log on to the Fusion web application.
Type the concatenated values of the workbook properties
RemoteServletPath into the address bar of your web browser. This corresponds to a URL similar to the following:
If the Oracle ADF Desktop Integration remote servlet is running, a web page returns displaying a message similar to the following:
ADF Desktop Integration Remote Servlet 11g (18.104.22.168.86)  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, it may mean that security is not configured correctly for the integrated Excel workbook and/or the Fusion web application. You can verify that your Fusion web application authenticates end users and is security-enabled by carrying out the following procedure.
To verify that a Fusion web application authenticates end users:
The Fusion web application requests you enter user credentials if it is security-enabled.
For more information about securing your integrated Excel workbook, see Chapter 11, "Securing Your Integrated Excel Workbook".
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 the Oracle ADF Desktop Integration module 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 the Oracle ADF Desktop Integration module.
Table C-1 Package Names for Log File Configuration
|To generate log file entries for this component...||Enter this package name...|
All Oracle ADF Desktop Integration server logic
Oracle ADF Desktop Integration remote servlet
Oracle 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
Captures all exceptions and errors.
Captures all non-fatal problem conditions.
Captures life cycle 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.
The Oracle ADF Desktop Integration module uses
adfdi-common object for client-side logging. By default, no log files are generated. For more information about
adfdi-common object, see Section C.3.2.3, "What You May Need to Know About adfdi-common Object".
adfdi-excel-client.dll.config configuration file determines what type of information the
adfdi-common object logs, where it logs it and in what format. For more information about the creation and configuration of the
adfdi-excel-client.dll.config file, see Section C.3.2.1, "How to Generate Log Files using a Configuration File". Table C-3 describes the log levels that client-side logging supports. You enter one of the values in this table in the
Users who do not have access to the directory that stores the
adfdi-excel-client.dll.config file can change the location where log files are output and the logging level by setting values for user environment variables. For more information, see Section C.3.2.2, "How to Configure Logging Using User Environment Variables".
Table C-3 Client-Side Logging Levels
Captures information about severe errors and exceptions.
Captures non-fatal conditions.
The Oracle ADF Desktop Integration module reports some non-fatal conditions to end users. It writes all non-fatal conditions in the log files.
Captures life cycle and control flow events.
Captures detailed information about the execution flow of the application.
You create an XML-based configuration file named
adfdi-excel-client.dll.config in the same directory as the
adfdi-excel-client.dll file. The parent element in the
adfdi-excel-client.dll.config file is
<configuration>. Table C-4 describes child elements and attributes that this configuration file contains and describes the attribute values that you supply to write different types of information to different formats of log file such as
For more information about the
TraceSource class and the configuration file that controls output by instances of this class, see the documentation for the Microsoft .NET Framework.
Table C-4 Child Elements and Attributes in the Configuration File
This element is a collection of source elements.
Specify values for the following attributes:
This element contains
The attribute values for these elements can define the type of information that is output to log files in addition to the format and location of the log files.
To create the configuration file for client-side logging:
In the Oracle ADF Desktop Integration Designer, click About Oracle ADF 11g Desktop Integration.
Click the Properties tab and note the value for the directory path that appears in the Configuration field.
For example, a directory path similar to the following:
C:\Documents and Settings\john\Local Settings\Apps\2.0\51O97ALD.VNY\OG48YJLC.Q0Y\orac..tion_ca85d24b89a948e6_000b.0001_61767b25443cf62e\adfdi-excel-client.dll.config
Navigate to the directory that you identified in Step 2.
Create an XML-based file named
adfdi-excel-client.dll.config in the directory with a
<configuration> parent element.
Add additional child elements and attributes as described in Table C-4.
Save the file.
Example C-1 shows a sample configuration file that generates two different log files with different formats (
.xml). These files capture different types of information such as
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>
For your reference, a sample
adfdi-excel-client.dll.config configuration file is available in the
You add two user environment variables to configure the logging level and location for XML log files. Use this option when you cannot access the
adfdi-excel-client.dll.config file to make changes to it.
Note:The directory that you specify as the location to store the
adfdi-excel-client.dll.configfile must exist before you configure the user environment variables discussed here. The generated log file will be in XML format.
To add or configure user environment variables on Windows:
Click the Windows Start button and then click Settings > Control Panel.
The Control Panel opens.
In the Control Panel, select and open System.
The System Properties dialog box opens.
Click the Advanced view tab and then click the Environment Variables button.
The Environment Variables dialog box opens.
In the input field User variables for username, click New and add variables as described in the following table.
|Enter a variable named...||With a value...|
||That defines the directory path and file name for the XML file that captures logging information.|
||That specifies the level of logging. Table C-3 lists valid values.|
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
TraceSource class, see Microsoft Developer Network.
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 Oracle ADF 11g Desktop Integration... in the Oracle ADF Desktop Integration Designer.
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.
This section describes the most common problems and their solutions.
SyncServletResponse. Version x was found, version y was expected