Skip Headers
Oracle® Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number E10139-02
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

C Troubleshooting an Integrated Excel Workbook

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:


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".

C.1 Verifying That Your Fusion Web Application Supports Desktop Integration

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:

  1. Log on to the Fusion web application.

  2. 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:


    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 ( [520]
    Response from oracle.adf.desktopintegration.servlet.DIRemoteServlet: OK.

C.2 Verifying End-User Authentication for Integrated Excel Workbooks

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:

For more information about securing your integrated Excel workbook, see Chapter 11, "Securing Your Integrated Excel Workbook".

C.3 Generating Log Files for an Integrated Excel Workbook

The Oracle ADF integration module can generate log files that capture information based on events triggered by the following pieces of software within the Oracle ADF Desktop Integration module:

C.3.1 About Server-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

Log level Description


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.

C.3.2 About Client-Side Logging

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".

The 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 adfdi-excel-client.dll.config file.

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

Level Description


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.

C.3.2.1 How to Generate Log Files using a Configuration File

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 .log,.txt, or .xml.

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

Element/Attribute Description


This element is a collection of source elements.

<source name ... switchValue>

Specify values for the following attributes:

  • name

    Set the value of this attribute to adfdi-common.

  • switchValue

    The level of logging. Possible values are described in Table C-3.

    Example C-1 demonstrates how you set a logging level of Verbose using the adfdi-common object.

    <source name="adfdi-common" switchValue="Verbose">


This element contains <add> elements.


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:

  1. In the Oracle ADF Desktop Integration Designer, click About Oracle ADF 11g Desktop Integration.

  2. 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
  3. Navigate to the directory that you identified in Step 2.

  4. Create an XML-based file named adfdi-excel-client.dll.config in the directory with a <configuration> parent element.

  5. Add additional child elements and attributes as described in Table C-4.

  6. Save the file.

    Example C-1 shows a sample configuration file that generates two different log files with different formats (.txt and .xml). These files capture 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"?>
          <source name="adfdi-common" switchValue="Verbose">
              <add type="System.Diagnostics.DelimitedListTraceListener"
                traceOutputOptions="ThreadId, ProcessId, DateTime"/>
              <add type="System.Diagnostics.XmlWriterTraceListener"

    For your reference, a sample adfdi-excel-client.dll.config configuration file is available in the ADFDI_HOME\bin\excel\samples directory.

C.3.2.2 How to Configure Logging Using User Environment Variables

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.


The directory that you specify as the location to store the adfdi-excel-client.dll.config file 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:

  1. Click the Windows Start button and then click Settings > Control Panel.

    The Control Panel opens.

  2. In the Control Panel, select and open System.

    The System Properties dialog box opens.

  3. Click the Advanced view tab and then click the Environment Variables button.

    The Environment Variables dialog box opens.

  4. 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...
    adfdi-common-file That defines the directory path and file name for the XML file that captures logging information.
    adfdi-common-level That specifies the level of logging. Table C-3 lists valid values.

  5. Click OK.

C.3.2.3 What You May Need to Know About adfdi-common Object

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 TraceSource class, see Microsoft Developer Network.

C.4 Exporting Excel Workbook Metadata

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:

  1. Click About Oracle ADF 11g Desktop Integration... in the Oracle ADF Desktop Integration Designer.

    The About Oracle ADF 11g Desktop Integration dialog box appears.

  2. 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.

  3. 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.

C.5 Common Desktop Integration Problems

This section describes the most common problems and their solutions.

Error message: [ADFDI-00127] A version mismatch was detected for SyncServletResponse. Version x was found, version y was expected
Cause: The client version of ADF Desktop Integration does not match the ADF Desktop Integration version in the web application.
Action: Uninstall client ADF Desktop Integration, and install the web application specific ADF Desktop Integration version. For more information about installing ADF Desktop Integration client, see Section 3.5, "Setting Up the Oracle ADF Desktop Integration Client Framework".
Error message: 404 Error - servlet not found
Cause: The web.xml deployment descriptor settings are not in sync with Workbook.RemoteServletPath property value.
Action: Open Workbook Properties editor and verify the Workbook.RemoteServletPath property value.
Error message: Uncaught exception thrown by method called through Reflection. (Exception from HRESULT: 0x80131604)
Cause: Microsoft .NET Programmability Support is not enabled.
Action: Enable Microsoft .NET Programmability Support. For more information, see Section 3.3, "Enabling Microsoft .NET Programmability Support".
Error message: Unable to attach: manifest not found for solution id 'fb43e1d8-0595-4c3f-8926-0de0494c37d3'
Cause: You tried to convert an Excel file without installing Oracle ADF Desktop Integration client.
Action: Install Oracle ADF Desktop Integration client. For more information, see Section 3.5, "Setting Up the Oracle ADF Desktop Integration Client Framework".