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:

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"
Section C.4, "Exporting Excel Workbook Configuration"
Section C.5, "Common ADF Desktop Integration Problems"

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

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

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

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

C.3 Generating Log Files for an 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."

C.3.1 About Server-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	`oracle.adf.desktopintegration`
ADF Desktop Integration remote servlet	`oracle.adf.desktopintegration.servlet`
ADF Desktop Integration HTTP filter	`oracle.adf.desktopintegration.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
`SEVERE (ERROR)`	Captures all exceptions and errors.
`WARNING`	Captures all irrecoverable problem conditions.
`INFO` or `CONFIG`	Captures lifecycle events such as servlet initialization, and so on.
`CONFIG`	Captures "heartbeat" events that echo status and execution context for each client-server interaction.
`FINE` `FINER` `FINEST`	These values generate increasing levels of diagnostic information.

C.3.2 About Client-Side Logging

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

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.

Figure C-1 Logging Tools in Oracle ADF Tab

The Logging group provides the following buttons:

Console

Displays the 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. The console displays entries that are logged while the console is open. Figure C-2 illustrates the 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, select and copy them to a text file.

Figure C-2 Logging Console Window

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

Figure C-3 Logging Output Level Dialog

Table C-3 Client-Side Logging Levels

Level	Description
`Critical`	Captures critical information.
`Error`	Captures information about severe errors and exceptions.
`Warning`	Captures irrecoverable conditions.
`Information`	Captures lifecycle and control flow events.
`Verbose`	Captures detailed information about the execution flow of the application.
`Off`	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.

Figure C-4 Add New Temporary Logging Output File Dialog

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

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>

C.3.2.3 How to Configure Logging Using User Environment Variables

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 Environment Variables to Configure Logging

Enter a variable named... With a value...

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. The directory that you specify here must exist before you add the `adfdi-common-file` variable. The generated log file will be in XML format.
`adfdi-common-level`	That specifies the level of logging. Table C-3 lists valid values.

adfdi-common-file

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 adfdi-common-file variable. The generated log file will be in XML format.

adfdi-common-level

That specifies the level of logging. Table C-3 lists valid values.

Click OK.

C.3.2.4 What You May Need to Know About the 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 the TraceSource class, see Microsoft Developer Network documentation.

C.4 Exporting Excel Workbook Configuration

You can export the XML configuration 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 configuration from an Excel workbook.

To export XML configuration 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 XML configuration to the specified file in the specified format.

C.5 Common ADF 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, "Installing ADF Desktop Integration."

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

Problem: Oracle ADF tab is not visible in your integrated Excel Workbook after installing ADF Desktop Integration: Cause: The ADF Desktop Integration add-in is not enabled in Excel.; Action: Enable the ADF Desktop Integration add-in in the Excel Options dialog. In Excel, click the Microsoft Office button, and then click Excel Options to open the Excel Options dialog. In the Add-Ins tab, open the Manage dropdown list, choose COM Add-ins, and click Go. In the COM Add-ins dialog, select the Oracle ADF Desktop Integration Add-in for Excel checkbox and click OK.

Error message: Programmatic access to Visual Basic Project is not trusted: Cause: Macro settings in Excel are not enabled.; Action: Verify that the Trust access to the VBA project object model checkbox in the Trust Center dialog is enabled. For more information, see Section 3.4, "Allowing ADF Desktop Integration to Access Microsoft Excel."

Problem: Edit Options dialog appears prompting for WebAppRoot when downloading an integrated Excel workbook from a Fusion web application: Cause: The adfdiExcelDownload filter is not properly configured in web.xml, and so the filter is not able to set the WebAppRoot property on the downloaded workbook.; Action: Ensure that the adfdiExcelDownload filter is properly configured in web.xml. Verify that the filter is listed in the correct order with respect to the ADF Library Web Application Support, if it is in use. Also verify that the filter mappings for the adfdiExcelDownload filter are correct (see Section E.2, "Configuring the ADF Desktop Integration Excel Download Filter.") You should also clear the directory into which browser downloads files.