3 Setting Up Your Development Environment

This chapter describes how to set up the development environment to integrate an Excel workbook with a Fusion web application, how to upgrade and remove ADF Desktop Integration, and how to localize the Visual Studio tools for Microsoft Office.

This chapter includes the following sections:

3.1 Introduction to Setting Up Your Development Environment

Setting up the development environment involves making sure that you have the correct versions of JDeveloper, Microsoft Office, and Microsoft Internet Explorer installed, as described in Section 3.2, "Required Oracle ADF Modules and Third-Party Software."

After verifying that you have the required software, and have enabled Microsoft .NET programmability, complete the setup of your development environment by:

  • Allowing ADF Desktop Integration to access Microsoft Excel

  • Installing ADF Desktop Integration

Note:

The instructions in this guide assume that you are using Windows 7 operating system and Microsoft Excel 2007. Note that the steps might be different for different editions of Windows and Excel.

3.2 Required Oracle ADF Modules and Third-Party Software

Before you begin to integrate your Excel workbook with a Fusion web application, ensure that you have the required Oracle ADF modules and third-party software installed and configured:

  • Oracle JDeveloper

    Install the current release of JDeveloper. ADF Desktop Integration is available as a JDeveloper feature.

  • 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

    ADF Desktop Integration supports the integration of Fusion web applications with the following types of Excel workbook:

    • Excel Workbook

      The default file format for Excel workbooks is the Excel XML-based file format (.xlsx).

    • Excel Macro-Enabled Workbook

      Workbooks in this format (.xlsm) use the Excel XML-based file format and can store VBA macro code.

    ADF Desktop Integration does not support the use of other Excel file formats. For more 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.

3.3 Configuring Excel to work with ADF Desktop Integration

You must configure Microsoft Excel settings to make it accessible from ADF Desktop Integration. You only need to perform this procedure once.

To allow Excel to run an integrated Excel workbook:

  1. Open Excel.

  2. Click the Microsoft Office button, and choose Excel Options.

  3. In the Excel Options dialog, choose the Trust Center tab, and then click Trust Center Settings.

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

    Figure 3-1 Excel Trust Center Dialog

    Excel Trust Center dialog

  5. Click OK.

3.4 Installing ADF Desktop Integration

When you run the ADF Desktop Integration setup tool, it verifies whether software in the following list is installed on the system where you want to install the framework. If one or more of these pieces of software is not installed, the setup tool automatically downloads and installs it in the order specified.

  1. Windows Installer 3.1

  2. Microsoft .NET Framework

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

    Notes:

    • Do not download the Client Profile edition of Microsoft .NET Framework as it is insufficient to run ADF Desktop Integration.

    • Installation of Microsoft .NET Framework may require you to restart the system where you install it. After the restart, the setup tool automatically recommences to finalize installation.

  3. 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. ADF Desktop Integration add-in

    You can install the ADF Desktop Integration add-in from JDeveloper, or from the adfdi-excel-addin-installer.exe installer available in MW_HOME\oracle_common\modules\oracle.adf.desktopintegration_11.1.1 directory. For more information about how to set up ADF Desktop Integration, see Section 3.4.1, "How to Set Up ADF Desktop Integration."

    Note that the ADF Desktop Integration installation is specific to the current Windows user profile. If you have multiple Windows user profiles on your system, and you want to use ADF Desktop Integration integrated Excel workbooks from some specific user profiles, you must log in to each user profile and install the ADF Desktop Integration add-in. For more information, see Section 3.4.1, "How to Set Up ADF Desktop Integration."

3.4.1 How to Set Up ADF Desktop Integration

You can install the ADF Desktop Integration add-in from JDeveloper, and then create and test integrated Excel workbooks.

Although you do not require administrator privileges to install the ADF Desktop Integration add-in, administrator privileges may be required to run the installer for additional software that the installer attempts to download and install. You should also ensure that the proxy settings for Internet Explorer are configured to allow access to *.microsoft.com because the installer attempts to automatically download missing prerequisite software from the Microsoft's website.

To install the Designer edition of ADF Desktop Integration:

  1. Open JDeveloper.

  2. From the Tools menu, choose Install ADF Desktop Integration, as shown in Figure 3-2.

    Figure 3-2 Tools Menu in JDeveloper

    Tools menu in JDeveloper

    Note:

    The Install ADF Desktop Integration menu option is available only on the Windows installation of JDeveloper.

  3. In the ADF Desktop Integration Installer page of Oracle ADF Desktop Integration Add-In for Excel wizard, click Install.

    Follow the instructions that appear in the dialog boxes to successfully install the required components. If you encounter an error during the installation process, an error message with a description appears, and installation is rolled back. For more details, check the adfdi-installer-log.txt error log file in the temp directory of the user profile.

  4. If prompted, click Yes to restart the system and complete the setup of ADF Desktop Integration.

Notes:

  • You can also install ADF Desktop Integration by running adfdi-excel-addin-installer.exe available in the MW_HOME/oracle_common/modules/oracle.adf.desktopintegration_11.1.1 directory. Before you run the installer, remember that the ADF Desktop Integration add-in installer does not enable designer features by default. You must enable the designer features in the add-in to create and edit integrated Excel workbooks.

    In the ADF Desktop Integration Installer page of the wizard, click Developer Options, and then in the Developer Options page select the Enabled option, and click Install.

  • Designer features are automatically enabled if you install ADF Desktop Integration from JDeveloper.

  • You can also install ADF Desktop Integration from the command line.

The ADF Desktop Integration files are installed in the /Oracle/Oracle ADF Desktop Integration Add-In for Excel subdirectory of the system-defined Local App Data directory (For example, C:\Users\johndoe\AppData\Local\Oracle\Oracle ADF Desktop Integration Add-In for Excel).

If you want to install ADF Desktop Integration for end users, see Section H.1, "Installing, Upgrading, and Removing ADF Desktop Integration."

3.5 Removing ADF Desktop Integration

Use the Microsoft Windows Control Panel to remove the ADF Desktop Integration add-in from the system where you set it up. After removing ADF Desktop Integration, you can no longer use integrated Excel workbooks on this system unless you reinstall ADF Desktop Integration.

To remove the ADF Desktop Integration add-in:

  1. Click the Windows Start button, and then choose Control Panel.

  2. In the Control Panel, select and open Programs and Features.

  3. Select the Oracle ADF Desktop Integration Add-in for Excel entry in the Uninstall or change a program window and click Uninstall.

Note:

If you have installed ADF Desktop Integration on multiple user profiles, you must remove it from each user profile.

3.6 Upgrading ADF Desktop Integration

To upgrade to a new version, run the ADF Desktop Integration installer from the new version. It is not necessary to uninstall the old version first.

You can run the installer from:

3.6.1 How to Migrate an Integrated Excel Workbook to the Current Version of ADF Desktop Integration

When you open the integrated Excel workbook after upgrading the ADF Desktop Integration add-in, the add-in detects and compares the ADF Desktop Integration version information of the workbook with the version installed on the client system. If required, you are asked to upgrade the configuration of the integrated workbook to the version installed on the client.

Note:

Integrated Excel workbooks created using an older ADF Desktop Integration client (version X) do not require migration on a system running a new version of ADF Desktop Integration client (version X+1), but integrated Excel workbooks used and saved with a newer client (version X+1) may no longer work with older clients (version X).

When the integrated Excel workbook is not compatible with the installed version of the ADF Desktop Integration client, a message is displayed when you open the workbook. In such a case, you should install the newer version of the ADF Desktop Integration client to interact with the newer workbook.

If you are migrating your integrated Excel workbooks created using the ADF Desktop Integration client of 11.1.1.3.0 version, or older, the Migrate Workbook dialog appears confirming your action.

To migrate an integrated Excel workbook after upgrading:

  1. Open the integrated Excel workbook.

    The Migrate Workbook dialog prompts you to migrate the workbook to the current version of ADF Desktop Integration.

    If you get one or more Microsoft Office Customization Installer error messages when you open the integrated Excel workbook, ignore the messages and continue. The error messages appear because ADF Desktop Integration cannot remove the old version information from the workbook before Excel detects it and reports the error.

  2. Click Yes to migrate the workbook. The ADF Desktop Integration migration process closes the workbook and then reopens it, ready to be used with the current version of ADF Desktop Integration.

3.7 Using an Integrated Excel Workbook with Older Versions of ADF Desktop Integration

When you open a workbook created, or last updated, by a newer version of ADF Desktop Integration on a system running an older version of ADF Desktop Integration, an error message is displayed if the workbook is incompatible with the installed client version. An integrated workbook and the installed ADF Desktop Integration client are incompatible if the first element of their Oracle Release number is different. For example, an integrated workbook created using version 12.1.4.0.0 of ADF Desktop Integration client is incompatible with the client from version 11.1.1.7.3.

Tip:

To see the release number of the installed client and integrated workbook, examine the values of ADF Desktop Integration and Workbook Edited by Version entries in Versions tab of the About ADF Desktop Integration dialog box.

At runtime, ADF Desktop Integration ignores an incompatible workbook. The data in the workbook is not removed, but ADF Desktop Integration treats the workbook as a non-integrated workbook and the following functionalities are affected:

  • ADF Desktop Integration does not respond to workbook events (for example, Activate and Startup)

  • ADF Button components do not respond to events

  • Worksheet command buttons do not appear in the Excel Ribbon

In design mode, or test mode, the workbook continues to function as expected, but you might notice some unknown exceptions and functionality issues.