4 System Administration for ADF Desktop Integration

This chapter describes system administration tasks for ADF Desktop Integration such as running the ADF Desktop Integration client installer from a web server and adjusting server configuration settings.

Note that before an end user can use the integrated Excel workbook, the ADF Desktop Integration add-in must be installed on the end user's system.

This chapter includes the following sections:

Section 4.1, "Installing and Upgrading ADF Desktop Integration."
Section 4.2, "ADF Desktop Integration Logs"
Section 4.3, "Security in ADF Desktop Integration"
Section 4.4, "Verifying the Client Version of ADF Desktop Integration"
Section 4.5, "Verifying Integrated Excel Workbook Metadata"
Section 4.6, "Common ADF Desktop Integration Error Messages and Problems"

4.1 Installing and Upgrading ADF Desktop Integration

You can make the ADF Desktop Integration installer available to end users to install, as described in Section 4.1.3, "How to Install the ADF Desktop Integration Add-in From a Web Server." Alternatively, you can install it, as described in the "Installing ADF Desktop Integration" section of the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

Note:

Installation of the ADF Desktop Integration add-in is specific to the current Windows user profile. If you have multiple Windows user profiles on a system, and you want to use ADF Desktop Integration integrated Excel workbooks in more than one of these user profiles, you must log in to each user profile and install the ADF Desktop Integration add-in.

When the ADF Desktop Integration installer runs, it verifies whether the required software is installed on the system. For more information about the required software, see the Section 4.1.1, "Prerequisites for Installing ADF Desktop Integration Add-in." In addition to installing the ADF Desktop Integration add-in, you (or the end user) must configure Microsoft Excel settings to make Excel accessible from ADF Desktop Integration, as described in Section 4.1.2, "Configuring the End User's Microsoft Excel to work with ADF Desktop Integration."

4.1.1 Prerequisites for Installing ADF Desktop Integration Add-in

Before you install the ADF Desktop Integration add-in, make sure that you have the required Oracle ADF modules and third-party software installed and configured:

Microsoft Windows

Microsoft Windows operating systems support the development and deployment of Excel workbooks that integrate with Fusion web applications. For more information about supported versions of Windows, see the "Oracle JDeveloper and Application Development Framework Certification Information" page on OTN at:

http://www.oracle.com/technetwork/developer-tools/jdev/index-091111.html
Microsoft Excel

For information about supported versions of Excel, see the "Oracle JDeveloper and Application Development Framework Certification Information" page on OTN at:

http://www.oracle.com/technetwork/developer-tools/jdev/index-091111.html

Note:

Microsoft Excel 2003 or older versions of Microsoft Excel are not supported.
Internet Explorer

Some features in ADF Desktop Integration use a web browser control from the Microsoft .NET Framework. This browser control relies on the local Internet Explorer installation to function properly.

ADF Desktop Integration uses Internet Explorer to render web pages inside Excel, regardless of other browsers installed on the system or any other browser set as the default browser.

The following software is required before ADF Desktop Integration add-in is installed. If this software is missing, the ADF Desktop Integration installer automatically downloads and installs it before installing the ADF Desktop Integration add-in.

Microsoft .NET Framework 4

The Microsoft .NET Framework 4 provides the runtime and associated files required to run applications developed to target the Microsoft .NET Framework. You can download the framework from http://www.microsoft.com/download/.
Microsoft Visual Studio 2010 Tools for Office Runtime

The Microsoft Visual Studio 2010 Tools for Office Runtime (Version 4) is required to run VSTO solutions for the Microsoft Office system. You can download the Microsoft Visual Studio 2010 Tools for Office Runtime from http://www.microsoft.com/download/.

4.1.2 Configuring the End User's Microsoft Excel to work with ADF Desktop Integration

The end user's installation of Microsoft Excel must be configured to make it accessible from ADF Desktop Integration. Perform this procedure once.

To allow Excel to run an integrated Excel workbook:

Open Excel.
Click the Microsoft Office button, and choose Excel Options.
In the Excel Options dialog, choose the Trust Center tab, and then click Trust Center Settings.
In the Trust Center dialog, choose the Macro Settings tab, and then click the Trust access to the VBA project object model checkbox, as shown in Figure 4-1.

Figure 4-1 Excel Trust Center Dialog
Click OK.

4.1.3 How to Install the ADF Desktop Integration Add-in From a Web Server

You can make the ADF Desktop Integration installer available from the web server where your Fusion web application is running. The installer is embedded in the oracle.adf.desktopintegration.war file and can be downloaded by the end user from the ADF Desktop Integration-enabled Fusion web application.

To download the installer from a web server:

Provide your end users with a URL in the following format that they can open in a web browser:

http://<hostname>:<portnumber>/<context-root>/adfdiRemoteServlet?excel-addin-installer

For example:

http://127.0.0.1:7101/summit/adfdiRemoteServlet?excel-addin-installer
Depending upon the browser, the end user will be prompted to download, or download and run, the adfdi-excel-addin-installer.exe installer file.

For more information about running the installer on a Windows system, see the "Installing ADF Desktop Integration" section in Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

Note:

Making the ADF Desktop Integration add-in installer available for download only works if the Fusion web application is an ADF Desktop Integration-enabled Fusion web application. The developer of a Fusion web application can implicitly enable ADF Desktop Integration by adding an integrated Excel workbook to the Fusion web application, as described in the "Adding an Integrated Excel Workbook to a Fusion Web Application" section, or explicitly, by configuring the application's web.xml file, as described in the "ADF Desktop Integration Settings in the Web Application Deployment Descriptor" appendix in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework. Adding an integrated Excel workbook to the Fusion web application may be preferable to configuring the web.xml file directly because JDeveloper makes many of the required configuration changes when the developer adds an integrated Excel workbook to the Fusion web application.

4.1.4 How to Upgrade the ADF Desktop Integration Add-in

An end user can upgrade ADF Desktop Integration in two ways.

Run the ADF Desktop Integration installer to upgrade.

For more information about downloading the installer, see Section 4.1.3, "How to Install the ADF Desktop Integration Add-in From a Web Server."
Open and run the integrated Excel workbook.

Each time the end user logs into the Fusion web application from an integrated Excel workbook, ADF Desktop Integration checks whether the version installed on the client matches the version on the server. If the versions do not match, the end user will be prompted to download the latest version of ADF Desktop Integration. If the end user accepts the prompt to install the latest version, the end user must also restart the Excel application after the installation completes for the change to take effect. For more information, see Section 4.4, "Verifying the Client Version of ADF Desktop Integration."

4.1.5 How to Patch ADF Desktop Integration

Patching involves copying a small collection of files over an existing installation. ADF Desktop Integration patch updates are delivered with Oracle Fusion Middleware patch updates. For more information, see the "Oracle Fusion Middleware Patching and Upgrade Overview" chapter of Oracle Fusion Middleware Patching Guide.

To patch an existing ADF Desktop Integration framework of Oracle Fusion Middleware 11g Patch Set 1 (Release 11.1.1.2.0) or Patch Set 2 (Release 11.1.1.3.0) environment to make it a Release 11.1.1.7.3 environment, you must upgrade the JRF domains to accommodate changes to ADF shared libraries. For more information about post-patching tasks for JRF Infrastructure and ADF shared libraries, see the "Post-Patching Procedures" chapter of Oracle Fusion Middleware Patching Guide.

Note:

The content in this section discusses patching the server environment that hosts the ADF Desktop Integration-enabled Fusion web application. Client installations of the ADF Desktop Integration add-in cannot be patched. That is, files cannot be copied over an existing installation of the ADF Desktop Integration add-in. You must run the newer version of the installer executable to upgrade the installation.

4.1.6 How to Run ADF Desktop Integration Installer from Command Line

The ADF Desktop Integration installer also supports command line options. Table 4-1 lists switches that you can specify with the installer executable file.

Table 4-1 ADF Desktop Integration Installer Command Line Switches

Switch	Description
`/help`	Displays a list of supported switches with description.
`/quiet`	Suppresses the interactive mode of the installer and does not install any missing prerequisite software. Before you install ADF Desktop Integration using the quiet mode, make sure that prerequisite software is installed on the end user's system. For more information about prerequisite software, see Section 4.1.1, "Prerequisites for Installing ADF Desktop Integration Add-in."
`DESIGNER=1`	Installs prerequisite software and the add-in with designer tools enabled. If prerequisite software is already installed, it will not be reinstalled when the installer runs. Application developers use the designer tools to configure integrated Excel workbooks. The designer tools are not intended for end users. For this reason, do not enable designer tools if installing the ADF Desktop Integration add-in for end users.
`/log <path>`	Runs the installer and directs the log output to the specified log file.

4.2 ADF Desktop Integration Logs

Based on various client and server events, logs are generated by ADF Desktop Integration. For more information about client-side log files, see the "About Client-Side Logging" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

You configure the generation of server-side log files for ADF Desktop Integration the same way as for other Oracle ADF modules. For more information, see the "About Server-Side Logging" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework. You can also use the Oracle Diagnostics Log Analyzer to view a hierarchical breakdown of elapsed time spent performing each ADF Desktop Integration servlet request. For more information, see the "Using the Oracle Diagnostics Log Analyzer to Analyze ADF Desktop Integration Servlet Requests" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

For more general information about logging in an Oracle Fusion Middleware environment, see the "Managing Log Files and Diagnostic Data" chapter in the Oracle Fusion Middleware Administrator's Guide.

4.3 Security in ADF Desktop Integration

If your Fusion web application enforces authentication, the integrated Excel workbooks also make sure that an authenticated end user session is established before data transfer happens between the workbooks and application. For more information, see the "Introduction to Security In Your Integrated Excel Workbook" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

4.3.1 End User Authentication

If end users are not prompted for user credentials while using integrated Excel workbooks and interacting with a secure Fusion web application, you need to investigate the security configuration of the Fusion web application. For more information, see the "Verifying End-User Authentication for Integrated Excel Workbooks" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

For more information about ADF Desktop Integration security, see the "Oracle ADF Desktop Integration Security whitepaper" on OTN at:

http://www.oracle.com/technetwork/developer-tools/adf/overview/index-085534.html

4.3.2 What You May Need to Know About Configuring Security in a Fusion Web Application

Note the following points before you secure your application:

For applications running in an environment using Oracle Access Manager, the system administrator should make sure that the URL for the ADF Desktop Integration Remote servlet is configured as a protected resource for Oracle Access Manager.

For more information, see the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.
For applications running in an environment using WebGate 11g, set the user-defined parameter filterOAMAuthnCookie to False.

For more information, see the chapter on registering partners (agents and applications) remotely in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Make sure that applications using ADF Desktop Integration have a security constraint configured in web.xml that protects the ADF Desktop Integration remote servlet.

The following code extract from web.xml shows an example security constraint protecting the remote servlet:

<security-constraint>
  <web-resource-collection>
    <web-resource-name>adfdiRemote</web-resource-name>
    <url-pattern>/adfdiRemoteServlet</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>valid-users</role-name>
  </auth-constraint>
</security-constraint>

When using Oracle WebGate and a SSL URL to access the Fusion web application (such as https:// ...) it may be necessary to configure WebGate's mod_wl_ohs.conf configuration file as follows:
```
<IfModule mod_weblogic.c>
        WLProxySSLPassThrough ON
        WLProxySSL ON
        MatchExpression /TestApp 
        WebLogicHost=test.host.com|WebLogicPort=7101|
</IfModule>
```
where /TestApp is the context root of your application, test.host.com is the host name and domain, and 7101 is the port number for the web application.
When opening an integrated Excel workbook, or any Microsoft Office document, directly (without downloading the file) from a link in the Fusion web application, the Windows Login dialog may appear twice asking for user credentials. This happens because Microsoft Office sends its own authentication request to the web server, making the Login dialog appear twice. End users may click Cancel and ignore the first authentication request.
Applications secured via a digital certificate where clients use https URLs to access the application should make sure that the certificate is valid. Valid certificates have host names that match the host to which they are deployed, have not expired, and have a valid path to a trusted issuing authority. In the case where the certificate is invalid, the client will be prompted during login to accept the invalid certificate.
ADF uses chunked encoding for some requests to the server. If you have any network devices between Excel and the web application server configured to block requests that do not contain a content length header, you should configure them to allow chunked encoding (no content length header). Some network devices such as content caching servers may have a default configuration that blocks requests with no content length header.

For more information about securing integrated Excel workbooks, see the "What You May Need to Know About Securing an Integrated Excel Workbook" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

4.3.3 What You May Need to Know About Resource Grants for Web Pages

In an integrated Excel workbook, each worksheet is bound to a specific page definition. Users' access to pages may be controlled by resource grants. If an end user is not authorized to work with a page definition, ADF Desktop Integration disallows all data transactions in worksheets bound to that page definition, displays a failure message, and disables those integrated worksheets. The end user can alter any existing data in the worksheet, but cannot download or upload it. The tracking of changes in ADF Table components is also disabled. The end user can continue to use ADF Desktop Integration features in other worksheets in the same workbook, provided those worksheets are bound to page definitions that the end user is authorized to work with.

The worksheet is re-enabled when the end user reopens the workbook and establishes a new session, provided that the end user has obtained the necessary resource grants for the corresponding page definition.

For more information about securing your Fusion web application, see the "Enabling ADF Security in a Fusion Web Application" chapter in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

4.4 Verifying the Client Version of ADF Desktop Integration

When an end user establishes a connection with the Fusion web application from the runtime integrated Excel workbook, ADF Desktop Integration verifies whether the client and the server versions are same, and issues a warning dialog if they do not match (see Figure 4-2).

Figure 4-2 Client-Server Version Check Warning Dialog

If the end user dismisses the warning dialog, ADF Desktop Integration attempts to continue to function normally, however using a client version that matches the server version is highly recommended to avoid unexpected behavior or errors.

4.4.1 What You May Need to Know About Client-Server Version Verification

Note the following points about client-server version verification in an ADF Desktop Integration project:

The client-server version verification is performed every time that the integrated Excel workbook establishes a session with the Fusion web application.
When the client and server version components match, there is no visible effect to end users.
The ADF Desktop Integration version running on the server can change at any time (for example, server upgrade), but the version verification is performed only when the user session is re-established.

Note:

The client-server version check warning dialog appears once per Excel session for a given combination of Fusion web application and client-server mismatch, regardless of how many times the user session is established or re-established.

4.5 Verifying Integrated Excel Workbook Metadata

To give end users the confidence that the workbook configuration has not been altered maliciously, ADF Desktop Integration verifies the integrity of the workbook metadata automatically using the Tamper-Check feature. For more information, see the "Checking the Integrity of an Integrated Excel Workbook's Metadata" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

4.5.1 How to Disable the Metadata Tamper-Check in the Fusion Web Application

By default, ADF Desktop Integration verifies that the workbook configuration metadata is not tampered with after the workbook's developer publishes the Excel workbook for end users. You can disable the metadata tamper-check by configuring a parameter in the deployment descriptor file (web.xml) of the Fusion web application.

Before you begin:

It may be helpful to have an understanding of how ADF Desktop Integration verifies the integrity of an integrated Excel workbook's metadata. For more information, see Section 4.5, "Verifying Integrated Excel Workbook Metadata."

To disable the metadata tamper-check in the Fusion web application:

Open the web.xml file of your Fusion web application.

Add an initialization parameter to the adfdiRemote servlet to disable the metadata tamper-check, as described in Table 4-2.

Table 4-2 Disabling Metadata Tamper-Check

Property Value

Property	Value
`Name`	Enter the name of the initialization parameter as follows: `TamperingCheck.Enabled` Note that the name is case-sensitive.
`Value`	Set the value of `TamperingCheck.Enabled` to `False`. Note that any value other than `False` will be interpreted as `True`.

Name

Enter the name of the initialization parameter as follows:

TamperingCheck.Enabled

Note that the name is case-sensitive.

Value

Set the value of TamperingCheck.Enabled to False.

Note that any value other than False will be interpreted as True.

Figure 4-3 shows the web.xml editor in JDeveloper.

Figure 4-3 Disabling the Metadata Tamper Check In JDeveloper

Shows how to disable the metadata tamper-check in JDev

Save the web.xml file.

The web.xml file of your Fusion web application will now have the TamperingCheck.Enabled entry:

<servlet>
        <servlet-name>adfdiRemote</servlet-name>
        <servlet-class>...</servlet-class>
        <init-param>
            <param-name>TamperingCheck.Enabled</param-name>
            <param-value>False</param-value>
        </init-param>
</servlet>

Rebuild and restart your Fusion web application.

If the TamperingCheck.Enabled parameter is not present in web.xml, tamper check is enabled. For more information about the web.xml file, see the "ADF Desktop Integration Settings in the Web Application Deployment Descriptor" appendix in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

4.5.2 How to Allow Missing Entries in the ADF Desktop Integration Client Registry

You can configure the metadata tamper-check so that a missing entry for the WorkbookID workbook property is allowed in the adfdi-client-registry.xml file.

Before you begin:

To allow missing entries in the metadata of the Fusion web application:

Open the web.xml file of your Fusion web application.

Add an initialization parameter to the adfdiRemote servlet to allow missing entries in the metadata as described in Table 4-3.

Table 4-3 Allowing Missing Entries in the Metadata

Property Value

Property	Value
`Name`	Enter the name of the initialization parameter as follows: `TamperingCheck.AllowMissingEntries` Note that the name is case-sensitive.
`Value`	Set the value of `TamperingCheck.AllowMissingEntries` to `True`. Any value other than `True` will be interpreted as `False`.

Name

Enter the name of the initialization parameter as follows:

TamperingCheck.AllowMissingEntries

Note that the name is case-sensitive.

Value

Set the value of TamperingCheck.AllowMissingEntries to True. Any value other than True will be interpreted as False.

Figure 4-4 shows the web.xml editor in JDeveloper.

Figure 4-4 Enabling Missing Metadata Entries In JDeveloper

Shows how to enable missing metadata entries In JDev

Save the web.xml file.

The web.xml file of your Fusion web application will now have *the TamperingCheck.AllowMissingEntries entry:

<servlet>
        <servlet-name>adfdiRemote</servlet-name>
        <servlet-class>...</servlet-class>
        <init-param>
            <param-name>TamperingCheck.AllowMissingEntries</param-name>
            <param-value>True</param-value>
        </init-param>
</servlet>

Rebuild and restart your Fusion web application.

If the TamperingCheck.AllowMissingEntries parameter is not present in web.xml, missing entries are not allowed. For more information about the web.xml file, see the "ADF Desktop Integration Settings in the Web Application Deployment Descriptor" appendix in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

4.6 Common ADF Desktop Integration Error Messages and Problems

While using or configuring the ADF Desktop Integration-enabled Fusion web application or workbooks, you might see error messages or encounter problems. The following list describes the most common error messages, their causes, and solutions.

You should also see the "Common ADF Desktop Integration Error Messages and Problems" section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework and the "ADFDI-00100 to ADFDI-55516" chapter in Oracle Fusion Middleware Error Messages.

Error message: Access to this web server is disabled because it is controlled by basic authentication and does not use Secure Socket Layer (SSL).

Cause: The user downloads and opens a workbook, published using Microsoft Office 2010, from the Fusion web application secured using basic authentication.

Action: By default, Microsoft Office 2010 applications disable basic authentication over a non-SSL connection. Use any of the following methods to resolve the error:

Use form-based authentication instead of basic authentication in the Fusion web application.
Download and save the workbook before opening it.
Enable SSL encryption.

If you want to use basic authentication without SSL, see Microsoft Support solution at http://support.microsoft.com/kb/2123563.

Error message: UnableToEstablishUnauthenticatedSessionException: ADFDI-00502: The client was unable to establish an unauthenticated session with the web application

Cause: Incorrect security configuration in the Fusion web application.

Action: Review and correct the security configuration. Make sure that the /adfdiRemoteServlet URL is protected by a <security-constraint> in web.xml.

If SSL is used with Oracle WebGate, you might also need to verify the settings in the mod_wl_ohs.conf file.

For example:

<IfModule mod_weblogic.c>
 WLProxySSLPassThrough ON
 WLProxySSL ON
 MatchExpression /TestApp 
 WebLogicHost=test.host.com|WebLogicPort=7101|
</IfModule>

where /TestApp is the context root of your application, test.host.com is the host name and domain, and 7101 is the port number for the web application.

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: Make sure 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 the "Configuring the ADF Desktop Integration Excel Download Filter" section in Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.) You should also clear the directory into which browser downloads files.

Problem: Login window does not close after submitting valid credentials in Oracle Access Manager environment: Cause: The /myApp/adfdiRemoteServlet was not properly added as a protected resource to the Oracle Access Manager configuration.; Action: Add /myApp/adfdiRemoteServlet as a protected resource to the Oracle Access Manager configuration.
For more information, see the chapter on managing policies to protect resources and enable SSO in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Problem: UserSessionRequiredException on login in Oracle Access Manager environment with WebGate 11g: Cause: The user defined parameter filterOAMAuthnCookie is not set in the WebGate 11g configuration.; Action: Set filterOAMAuthnCookie to false in the WebGate 11g configuration.
For more information, see the chapter on registering partners (agents and applications) remotely in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager.

Problem: The DIRemoteServlet returns Invalid XML: unexpected end of response error message: Cause: An exception has occurred in the ADF Model code, custom application module, or in the view object.; Action: Check the server logs for more information.