C Troubleshooting an Integrated Excel Workbook

Describes how to troubleshoot an integrated Excel workbook and generate log files when you encounter problems during development.

This appendix includes the following sections:

• Verifying That Your Fusion Web Application Supports ADF Desktop Integration

• Generating an ADF Desktop Integration Diagnostic Report

• Troubleshooting Connection Problems to Fusion Web Applications

• Verifying End-User Authentication for Integrated Excel Workbooks

• 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 information about the property inspector, see Using the Property Inspector.

Verifying That Your Fusion Web Application Supports ADF Desktop Integration

Using a server ping test, 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.

For Fusion web applications that enforce authentication, you can use the server ping test to confirm that the proper authentication configuration is in place for the ADF Desktop Integration servlet URL.

ADF Desktop Integration relies on various Internet Explorer specific settings. For this reason, please perform the verification test using Internet Explorer.

To verify that the ADF Desktop Integration remote servlet is running:

1. 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/summit/adfdiRemoteServlet

   If the ADF Desktop Integration remote servlet is running, a web page returns displaying a message similar to Figure C-1.

   Figure C-1 ADF Desktop Integration Remote Servlet

   
   Description of "Figure C-1 ADF Desktop Integration Remote Servlet"

Generating ADF Desktop Integration Diagnostic Reports

ADF Desktop Integration provides a number of tools so that you and end users can diagnose and resolve issues that may occur in the client-side environment.

These include the Client Health Check Tool, described in Running the Client Health Check Tool. This determines if the client environment is configured correctly and provides options to resolve some commonly-encountered issues. You or end users can also generate a diagnostic report (adfdi-diagnostic-report.txt) from an integrated Excel workbook, as described in the following section.

How to Generate the ADF Desktop Integration Diagnostic Report

You or your end users can generate the diagnostic report by clicking the Save Diagnostic Report menu entry that ADF Desktop Integration adds to Microsoft Excel’s File > Add-Ins menu, as shown in Figure C-2.

Figure C-2 File Menu to Save Diagnostic Report

The location of this menu entry depends on the version of Microsoft Excel that you use. Figure C-2 shows the location of this menu entry in Microsoft Excel 2013.

Alternatively, you or end users can generate the diagnostic report from the About dialog.

To generate the ADF Desktop Integration diagnostic report from the About dialog:

1. Open the integrated Excel workbook.
2. If you have opened the integrated Excel workbook in the design mode, click the About button in the Workbook group of the Oracle ADF tab.

   If you have opened the integrated Excel workbook in runtime mode, click the About button of the runtime ribbon tab.

3. Click the Diagnostic Report button of the About dialog.
4. Save the diagnostic report text file. By default, the file is saved as adfdi-diagnostic-report.txt in the Desktop directory (for example, C:\Users\<USER_NAME>\Desktop).
5. The Diagnostic Report dialog opens describing the location of the saved file. Click OK to open the file in the default text editor.

What You May Need to Know About the ADF Desktop Integration Diagnostic Report

The diagnostic report is a text file and includes a variety of information such as:

• ADF Desktop Integration add-in version

• Microsoft Windows version

• Microsoft Excel version

• Values of all properties from the Version tab of the About dialog

• Values of all properties listed in the Properties tab of the About dialog

• List of Excel COM add-ins

• Branding items from the About tab, if the report is generated at runtime

• ADF Desktop Integration servlet version, if the report is generated after a valid login

You can open and edit the text file in any text editor, or Excel. Each row in the file consists of a key-value pair separated by tabs.

Before end users send the diagnostic file to you, ask them to review the report and remove any sensitive information that they do not want to share.

Troubleshooting Connection Problems to Fusion Web Applications

ADF Desktop Integration provides end users with connection failure reports to help diagnose the cause of connection failures from integrated Excel workbooks to Fusion web applications.

A connection failure report contains information that ADF Desktop Integration generates when an attempt to connect to a Fusion web application fails or the end user cancels the connection attempt. Figure C-3 shows the dialog that appeared when the EditCustomers.xlsx workbook failed to connect to the Summit sample application because the latter application was offline. End users click Save Report to save the report to a directory on their machine.

Figure C-3 End User’s Dialog to Save a Connection Report

Before end users send the connection failure report file to you, ask them to review the report and remove any sensitive information that they do not want to share. The following example shows an extract of the report generated in Figure C-3.

Report: Oracle ADF Desktop Integration (ADFdi) Connection Failure Report
Generated: (UTC) 04/12/2015 09:47:13
Language: en-US

*** NOTE: this file contains detailed diagnostic information. Review the contents and edit out any information you do not wish to share with third parties. ***

=== Summary ===

Failure Phase
	AuthenticationTest

Failure Reason
	UnexpectedHttpStatusException - ADFDI-00501: An unexpected status: 404 (NotFound) was returned from the server while requesting the URL: http://127.0.0.1:7101/summit/adfdiRemoteServlet

ADFdi servlet URL
	http:// 127.0.0.1:7101/summit/adfdiRemoteServlet
...

For more information about troubleshooting connection problems, see the documents that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc IDs 2014348.1 and 2094772.1.

Verifying End-User Authentication for Integrated Excel Workbooks

If 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, in the web browser's address bar, enter the URL that you used to verify whether ADF Desktop Integration remote servlet is running. See Verifying That Your Fusion Web Application Supports ADF Desktop Integration. 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 Securing Your Integrated Excel Workbook.

Generating Log Files for an Integrated Excel Workbook

ADF Desktop Integration can generate log files that capture information based on events triggered by the server-side and client-side software.

The following pieces of software within ADF Desktop Integration trigger events:

• HTTP filter and the ADF Desktop Integration remote servlet on the web server (server-side logging)

  For information about server-side logging, see About Server-Side Logging.

• Excel workbook which you integrate with your Fusion web application (client-side logging)

  For information about client-side logging, see About Client-Side Logging.

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 logging.xml. You can also use Oracle Diagnostic Logging Configuration of JDeveloper to configure the logging levels specified in the logging.xml file. For information about using the JDeveloper debugging tools and ADF Logger, see Using the ADF Logger in Developing Fusion Web Applications with Oracle Application Development Framework.

Table C-1 describes the package names that you supply as attribute parameters to the <logger> elements in the 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 HTTP filter	oracle.adf.desktopintegration.filter

Using the Oracle Diagnostics Log Analyzer to Analyze ADF Desktop Integration Servlet Requests

Using the Oracle Diagnostics Log Analyzer, you can view a hierarchical breakdown of elapsed time spent performing each ADF Desktop Integration servlet request. The hierarchical breakdown also includes the time spent in other ADF components, such as the ADF Model layer. For information about using the log analyzer for viewing web requests, see How to Use the Log Analyzer to View Log Messages in Developing Fusion Web Applications with Oracle Application Development Framework.

Tip:

The hierarchical breakdown can be helpful in identifying performance bottlenecks due to unusually long execution times.

In order to log a complete hierarchy tree of ADF event messages, including ADF Desktop Integration events, specify log level CONFIG for the oracle.adfdiagnostics package. For more information about the oracle.adfdiagnostics logger, see How to Create an Oracle ADF Debugging Configuration in Developing Fusion Web Applications with Oracle Application Development Framework.

About Client-Side Logging

ADF Desktop Integration provides a number of methods to create log files of activity that occur within the ADF Desktop Integration add-in. Logging is always enabled at a high level, the Information level. These logs are in plain text format and include the basic user steps as well as any errors and warning. For information, see What You May Need To Know About Always-On Logging.

In some cases, you may need more detailed logs to troubleshoot a particular problem. There are several methods for producing detailed logs at the Verbose level. The simplest method is to enable transient verbose logging by selecting Enable Logging... from the Excel add-in menu that ADF Desktop Integration adds to Microsoft Excel. These logs are in XML format and include a very detailed account of client-side activity. For information, see Enabling Transient Verbose Logging.

Additionally, there are two other methods for controlling client logs:

• Using the Logging options that the Oracle ADF tab exposes, as described in How to Configure Logging in the Oracle ADF Tab.

• Using the ADF Desktop Integration Configuration file, as described in About the ADF Desktop Integration Configuration File.

• Configuring environment variables, as described in How to Configure Logging Using User Environment Variables.

Consider using one of the latter two options if you want to capture log information that spans one or more integrated Excel workbook restarts and/or you want to configure a lower logging level than verbose.

Table C-2describes the different log levels that you can enable for client-side logging.

What You May Need To Know About Always-On Logging

By default, ADF Desktop Integration enables logging at the Information level to a text file in the adfdi-logs sub-directory of one of the following directories, listed in order of preference:

• %TEMP%\oracle\adfdi-logs

• %TMP%\oracle\adfdi-logs

• %LocalAppData%\temp\oracle\adfdi-logs

• %SystemDrive%\oracle\adfdi-logs

To determine which of the above directories ADF Desktop Integration uses to store log file information, see the Log Files property that you can view from the About dialog of your integrated Excel workbook, as shown in Figure C-4.

Figure C-4 Directory Location of Always-on Log Files

ADF Desktop Integration creates a new log file each time you start a new Excel session with an integrated Excel workbook. It uses the convention adfdi-log-timestamp.txt when naming log files where timestamp is the time at which you start the integrated Excel workbook (for example, adfdi-log-2015-11-25-191209.txt).

Note:

ADF Desktop Integration purges the oldest always-on log file(s) in the folder when the folder reaches a certain size.

For information, see the document that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc ID 2094378.1.

Enabling Transient Verbose Logging

You or your end users can enable verbose logging from a menu in the active integrated Excel workbook. ADF Desktop Integration writes verbose log information to a file in a directory you specify when you enable the logger from the menu.

The filename that ADF Desktop Integration creates when you enable this logging has the following format:

adfdi-log-timestamp.xml

Where timestamp is the time at which you enable logging. For example, adfdi-log-2015-11-24-145055.xml.

The menu options you choose to enable this logging depend on the version of Microsoft Excel that you use. Figure C-5 shows the location of this menu entry in Microsoft Excel 2013.

Figure C-5 Excel File Menu to Enable Verbose Logging

Description of "Figure C-5 Excel File Menu to Enable Verbose Logging"

Once you quit Microsoft Excel, ADF Desktop Integration stops logging information to the log file.

To enable transient verbose logging:

1. Launch Microsoft Excel from the Windows menu but do not open the integrated Excel workbook with the issue for which you want to capture verbose log data.

2. From the Office or File menu of Excel, select Add-Ins > ADF Desktop Integration > Enable Logging, as shown in Figure C-5.

3. Save the log file to a location of your choosing or use the default Desktop location that the Save Logging Data As dialog proposes. Note the log file name and location for later reference.

4. Open the integrated Excel workbook and repeat the steps to reproduce the issue for which you want to capture verbose log data.

5. Once you have completed the steps, you can quit Microsoft Excel. Once you quit Microsoft Excel, ADF Desktop Integration stops logging verbose data to the log file you created in Step 3.

Tip:

Save a diagnostic report with information about the environment where ADF Desktop Integration runs that you can submit to Technical Support with the verbose log data that you have captured for your issue. From the Office or File menu of Excel, select Add-Ins > ADF Desktop Integration > Save Diagnostic Report, as shown in Figure C-5.

For information, see the document that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc ID 2094434.1.

How to Configure Logging in the Oracle ADF Tab

The Oracle ADF Tab, shown in Figure C-6, provides a Logging group of menu options that are available in both design mode and test mode.

Figure C-6 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. Figure C-7 illustrates the Logging Console window with 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.

  Figure C-7 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-2 describes the log levels that client-side logging supports. The log levels are cumulative as you read down the list in Table C-2. That is, the Information level includes the data logged in the Critical, Error, and Warning levels, but not the Verbose level.

  Figure C-8 Logging Output Level Dialog

  

  Table C-2 Client-Side Logging Levels

  Level	Description
  Critical	Captures critical information.
  Error	Captures information about severe errors and exceptions.
  Warning	Captures information about warnings.
  Information	Captures lifecycle and control flow events. This is the default value.
  Verbose	Captures detailed information about the execution flow of the application.

  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-9 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 exit Excel, 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 can determine the level of information logged by the ADF Desktop Integration add-in.

  For information about the creation and configuration of the ADF Desktop Integration configuration file, see About the ADF Desktop Integration Configuration File.

About the ADF Desktop Integration Configuration File

The ADF Desktop Integration configuration file is saved as adfdi-excel-addin.dll.config. 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 information about elements of the configuration file, see the Configuration File Schema for the .NET Framework section in Microsoft Developer Network documentation. For 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 an .xml log file. 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.XmlWriterTraceListener"
            name="adfdi-common-excel.xml"
            initializeData="c:\logs\adfdi-common-excel.xml"
            traceOutputOptions="ThreadId, ProcessId, DateTime"/>
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
</configuration>

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.

For information, see the How To Obtain Log Files For ADF Desktop Integration document that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc ID 2012985.1.

Tip:

Be sure to exit Excel completely prior to configuring the environment variables.

To add or configure user environment variables on Windows:

1. Click the Windows Start button and then click Control Panel.
2. In the Control Panel, click System, and then Advanced System Settings.
3. In the Advanced tab of System Properties dialog, click Environment Variables.
4. In the Environment Variables dialog, click New under the User variables for username input field, and add variables as described in the Table C-3.

   Table C-3 User Environment Variables to Configure Logging

   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-2 lists valid values.

5. Click OK.

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. To know the location of the log file, check the Log Files attribute in the Properties tab of the About dialog.

For information about the TraceSource class, see Microsoft Developer Network documentation.