C Troubleshooting an Integrated Excel Workbook

This appen dix 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 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 Metadata"

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

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:

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:8988/FusionApp/adfdiRemoteServlet

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 (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, 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:

Type the concatenated values of the workbook properties WebAppRoot and Login.ProtectedWebPage into the address bar of your web browser. This corresponds to a URL similar to the following:

http://hostname:8988/FusionApp/faces/secured/SecurePage.jspx

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

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:

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 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. For more information about this file and about using the JDeveloper debugging tools, see the "Using the ADF Logger and Business Component Browser" 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.desktopintegration`
Oracle ADF Desktop Integration remote servlet	`oracle.adf.desktopintegration.servlet`
Oracle 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 le vel.

Table C-2 Server-Side Logging Levels

Log level	Description
`SEVERE (ERROR)`	Captures all exceptions and errors.
`WARNING`	Captures all non-fatal problem conditions.
`INFO` or `CONFIG`	Captures life cycle 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

The Oracle ADF Desktop Integration module uses an object (adfdi-common) which is an instance of the TraceSource class from the System.Diagnostics namespace in the Microsoft .NET Frame work. 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. By default, no log files are generated.

A configuration file (adfdi-excel-client.dll.config) 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
`Error`	Captures information about severe errors and exceptions.
`Warning`	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.
`Information`	Captures life cycle and control flow events.
`Verbose`	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
sources	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">
`<listeners>`	This element contains `<add>` elements.
`<sharedListeners>`	This element contains listeners that any source or trace element can reference.
`<add>`	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. You can also use `<add>` elements to refer to shared trace listeners that are defined in a `<sharedListeners>` element. In Example C-1, the third `<add>` element refers to a listener `adfdi-common-excel.xml`. This listener is defined in the `<sharedListeners>` element.

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 three different log files with different formats (.log, .xml, and .txt). 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"?>
<configuration>
   <system.diagnostics>
      <sources>
         <source name="adfdi-common" switchValue="Verbose">
            <listeners>
               <add type="System.Diagnostics.TextWriterTraceListener" name="adfdi-excel-common.log"
                   initializeData="d:\temp\adfdi-excel-common.log" traceOutputOptions="DateTime"/>
               <add type="System.Diagnostics.DelimitedListTraceListener" name="adfdi-excel-common.txt"
                   initializeData="d:\temp\adfdi-excel-common.txt" delimiter="|"
                   traceOutputOptions="ThreadId, ProcessId, DateTime"/>
   <add name="adfdi-excel-common-xml"/>  
            </listeners>
         </source>
      </sources>
<sharedListeners>
         <add name="adfdi-excel-common-xml" initializeData="d:\temp\adfdi.xml"
            traceOutputOptions="None"/>
      </sharedListeners>
   </system.diagnostics>
</configuration>

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 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.config file must exist before you configure the user environment variables discussed here.

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

Click OK.

C.4 Exporting Excel Workbook Metadata

You can export the XM L 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 D11g 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.

The integrated Excel workbook exports the metadata to the specified file in the specified format.