User Guide to Install ADF Desktop Integration Client

Author: Zeesha Currimbhoy(zeesha.currimbhoy@oracle.com)

Contents

1. Pre-requisites to Installing ADF Desktop Integration Client..........................................................4

1.1 Supported Operating Systems....................................................................................................4

2. Steps to Install ADF Desktop Integration Client Framework.........................................................5

2.1 Step 1 – Install Microsoft Office 2007......................................................................................5

2.2 Step 2 – Install Internet Explorer 7............................................................................................5

2.3 Step 3 – Ensure .NET Programmability Support.......................................................................5

2.4 Step 4 – Allow Microsoft Excel to run an Integrated Workbook..............................................7

2.5 Step 5 – Install the ADF Desktop Integration Client.................................................................8

2.6 Step 6 – Configure Security Settings to allow access to remote hosts in your Excel workbook10

3. Removing ADF Desktop Integration Client Framework...............................................................13

4. Using the Desktop Integration Client with different instances of JDeveloper on the server......14

5. Working with an ADF Desktop Integrated Worksheet..................................................................15

5.1 ADFDi Functionality in the Integrated Worksheet..................................................................15

5.2 Changing the Web Applications Root.....................................................................................15

5.3 Importing Data into an Integrated Excel Workbook................................................................16

6. FAQ / Troubleshooting......................................................................................................................18

6.1 COM Exception HRESULT: 0x800A03EC............................................................................186.1.1 Exception Stack Trace:............................................................................................................................186.1.2 Circumstances under which issue is observed.........................................................................................186.1.3 Workaround.............................................................................................................................................18

7. References............................................................................................................................................20

Revision HistoryDate Name Versio

nChange Reference

11-17-2008 Zeesha Currimbhoy

1.0 Document Creation

11-18-2008 Zeesha Currimbhoy

1.1 Modifications based on suggestions by Alex Removed details of JDev from section 4 Added Section 5.3

06-29-2009 Zeesha Currimbhoy

1.2 Added location for ADFDi Client download

10-13-2009 Zeesha Currimbhoy

1.3 Added troubleshooting Section

1. Pre-requisites to Installing ADF Desktop Integration Client

1.1 Supported Operating Systems

Microsoft Windows XP Operating System

Microsoft Vista Operating System

2. Steps to Install ADF Desktop Integration Client Framework

2.1 Step 1 – Install Microsoft Office 2007

Install Microsoft Office Excel 2007 on your Windows Desktop machine.

If you have not yet installed Microsoft Office 2007, during the install, enable ‘Microsoft Excel Programmability Support’ under the features to install.

If you already have Microsoft Office 2007, you most probably already have ‘Microsoft Excel Programmability Support’ enabled. Anyway, in the later steps we will be checking just to make sure that it is enabled. So for now do not worry about this and continue with the remaining steps.

Microsoft Office 2007 can be downloaded from MyDesktop (http://mydesktop.oraclecorp.com)

2.2 Step 2 – Install Internet Explorer 7

It is not mandatory, but recommended that you have Internet Explorer 7 installed. Before proceeding, we recommend that you install Internet Explorer 7.

Note: Parts of the Oracle ADF Desktop Integration module use a browser control that is hosted in a Microsoft .NET Framework web browser control. Internet Explorer 7 is the only web browser that supports this feature and is hence required by the ADF Desktop Integration Framework.

Internet Explorer 7 can be downloaded from: http://www.microsoft.com/windows/downloads/ie/getitnow.mspx

2.3 Step 3 – Ensure .NET Programmability Support

Ensure that for Microsoft Office .Net Programmability Support is enabled.

Microsoft Office Excel 2007 must have Microsoft .NET programmability support enabled before you can set up the Oracle ADF Desktop Integration module and start development of an Excel workbook that integrates with a Fusion web application. If you enabled Microsoft .NET programmability support during installation of Microsoft Office Excel 2007, no further action is required.

If you are not sure if you have enabled .NET programmability support for Microsoft Excel, it can be checked or installed by:

1. Go to Start -> Settings -> Control Panel

2. The Control Panel Opens. Double Click on Add Remove Programs

3. Browse the list of programs to locate Microsoft Office 2007. Click on Microsoft Office 2007 and press the ‘Change’ button located alongside

4. The change installation dialog opens.

Select ‘Add Remove features’ on the dialog options (see image below) and click Continue

Figure 1 - Change Microsoft Office Installation dialog

5. You will be presented with a dialog that lists all the features of Microsoft Office and their status (whether they have been installed or not installed).

Browse the list of features to locate the ‘.NET Programmability Support’ feature under ‘Microsoft Office Excel’ (see image below).

6. Note the icon beside the ‘.NET Programmability Support’ feature to know the status of installation. If the icon looks like (a small green dot on it) it means that Microsoft Excel has the ‘.NET Programmability Support’ feature enabled.

You can do not need to do anything further and you can safely exit.

If the icon looks like it means that you do not have ‘.NET Programmability Support’ enabled for Microsoft Excel.

To enable ‘.NET Programmability Support’

a. Click the icon and select ‘Install’.

b. Press Continue.

c. Microsoft configures ‘.NET Programmability Support’ for Excel.

2.4 Step 4 – Allow Microsoft Excel to run an Integrated Workbook

Microsoft Excel 2007 needs to be configured so that it will allow you to run an ADFDi Enabled Integrated workbook. In order to do this, you need to configure the ‘Trust Access to the VBA project model’ checkbox as detailed below.

To configure Excel to allow it to run an Integrated Workbook:

1. Open Excel by pressing Start -> Programs -> Microsoft Office -> Microsoft Excel 2007

2. Click on the Microsoft office button and then click on ‘Excel Options’ (See image below)

3. Click the Trust Center tab and then click Trust Center Settings

Click the Microsoft office button

Click Excel Options

4. Click the Macro Settings tab and the check the ‘Trust access to VBA project object model’ checkbox

5. Click OK

2.5 Step 5 – Install the ADF Desktop Integration Client

The ADF Desktop Integration Client Framework requires the following prerequisites.

1. Windows Installer 3.1

Select Macro Settings

Select this checkbox

Click Trust Center

Click Trust Center Settings

2. Microsoft .NET framework 3.5

Note: Installation of the Microsoft .NET framework might require you to restart your machine. After you restart the installation automatically recommences.

3. Microsoft Visual Studio Tools for Microsoft Office system version 3.0 runtime (x86)

Note 1: The ADF Desktop Integration Client setup utility checks to see if any of the pre-requisites are missing and if required attempts to download and install them from the Microsoft site. For this purpose make sure that you have an internet connection to allow for the downloads and that your internet proxy settings are configured to allow access to *.microsoft.com. You need not worry about this because for the most part you would already be allowed access to Microsoft.com.

Note 2: Though the setup utility itself does not require administrative privileges, some of the pre-requisites may require you having administrative privileges.

To install the ADF Desktop Integration Client

1. Download or get the ADF Desktop Integration Client Setup utility. Save and extract the client setup utility (zip file) in a folder on your computer. The Client Setup utility can be downloaded from:

ADFDi Client Installer

Note: Make sure that you have the correct version of the ADF Desktop Integration Client Utility. The ADFDi Client setup install should match the ADF Di version or libraries that are present on the server you want to interact with. In some way it is mapped to the builds of JDeveloper. This would indicate that when you migrate to a new build of JDeveloper you need to remove your existing ADFDi Client and reinstall the ADFDi client that shipped with the new JDeveloper build.

2. Ensure that your internet proxy settings in Internet Explorer are configured to allow access to *.microsoft.com. This is required because if the required pre-requisites are not installed on your machine, the installer will attempt to download them from microsoft.com. For the most part this will not be an issue because we are already allowed access to Microsoft.com. However, if you want to be extra cautious you can add Microsoft.com to the list of trusted sites under Internet Explorer settings. Even if you do not do this, you would most likely not face any issues with the installation.

3. Run the setup.exe of the ADF Desktop Integration Client utility.

If the required pre-requisites are not installed, the installer will attempt to install them for you.

Note: Some of the pre-requisites (Microsoft .NET framework 3.5) may require a restart of the computer. After you restart the installation automatically recommences.

4. Once the pre-requisites are installed, you will be prompted with an Unknown Publisher Dialog confirming whether you want to install the ADFDi utility.

5. Follow the instructions in the dialog boxes that appear to successfully install the client utility.

6. After the installation completes, check to see if it has successfully installed.

Note: ADF Desktop Integration Client Framework appears as ‘Oracle ADF 11g Desktop Integration’ under the Add remove programs.

To check for successful installation:

1. Go to Start -> Settings -> Control Panel

2. The control panel opens up. Double click on Add Remove Programs

3. Navigate the list of programs to see if there is an entry called ‘Oracle ADF 11g Desktop Integration’. If this is present it means that your ADF Client has successfully installed.

With this, you have successfully completed the install of the ADFDi client framework install. You are now in a position to be able to run ADFDi integrated Excel Workbooks on your Windows environment.

2.6 Step 6 – Configure Security Settings to allow access to remote hosts in your Excel workbook

We are now ready to start working with an Integrated Excel workbook.

Before you run an integrated Excel Workbook on your windows environment, you need to configure the security settings within Excel to allow access to your remote host. To do this, we assume that you now have an integrated Excel workbook or know the hostname that your Excel workbook interacts with.

To configure security settings on your Excel workbook, you need to add the remote hostname under the list of trusted locations.

To know what location you need to add under the list of trusted locations, note the address in your web browser that you use to access your ADF application.

For example, if your ADF page is at the location : http://myserver.us.oracle.com:9999/my context root/faces/index.jspx , you would add http://myserver.us.oracle.com:9999/my context root/ to your list of trusted locations.

To add the remote hostname under the list of trusted locations in Excel:

1. Open Excel by going to Start -> Programs -> Microsoft Office -> Microsoft Office Excel 2007

2. Click on the Microsoft office button and then click on ‘Excel Options’ (See image below)

3. Click the Trust Center tab and then click Trust Center Settings

4. Click the Trusted Locations tab.

5. Select the ‘Allow Trusted Locations on my network (not recommended)’ checkbox

6. Click the ‘Add New Location’ button (refer figure below)

Click the Microsoft office button

Click Excel Options

Click Trust Center

Click Trust Center Settings

7. The ‘Add New Location’ dialog box opens (as shown below). Enter the hostname of the server that your Integrated Excel workbook will be accessing.

8. Select the checkbox ‘Subfolders of this location are also trusted’

9. Click Ok.

Microsoft Office Excel is now configured to allow the integrated excel workbooks to access your remote hosts.

Click ‘Trusted Locations’

Select ‘Allow trusted locations’ checkbox

Click ‘Add new location’ button

3. Removing ADF Desktop Integration Client FrameworkTo uninstall ADF Desktop Integration Client use the Windows Add Remove programs utility

1. Click on Start -> Settings -> Control Panel

2. The control panel opens. Double click on Add Remove Programs

3. Find the entry Oracle ADF 11g Desktop Integration in the list of programs and click Remove

4. You will be prompted with a dialog to confirm if you want to remove the customization (see image below). Click Ok.

5. Windows uninstalls ADF Desktop Integration Client from your computer. Make sure that it has been successfully removed by checking that the ‘Oracle ADF 11g Desktop Integration’ entry is no longer present under the Add Remove Programs list.

4. Using the Desktop Integration Client with different instances of JDeveloper on the serverYou can have only one active installation of the ADF Desktop Integration Client on your Windows machine.

If for some reason you want to install a different version of the Desktop Integration Client you need to:

1. Uninstall your Desktop Integration Client using the method described under Removing ADF Desktop Integration Client Framework

2. Get the new version of ADF Desktop Integration Client Framework

3. Follow the procedure described under ‘Steps to Install ADF Desktop Integration Client Framework’ to install the new Client

5. Working with an ADF Desktop Integrated Worksheet

5.1 ADFDi Functionality in the Integrated Worksheet

When you first open an ADF Desktop Integrated worksheet, you will not see any major differences between a normal Excel worksheet and an ADF Di enabled one. All the ADF Di provided functionality that is available to you can be seen under the Excel tab called ‘Add Ins’. This is where all the custom ADF Di functionality will be provided (see figure below).

5.2 Changing the Web Applications Root

The Web Applications Root is the location of the web application on the server that the Integrated Excel spreadsheet interacts with. This is set at the time of creation of the spreadsheet and is pre-configured when you download your Excel spreadsheet. If for some reason you want to change the location of the Web Applications root you can do so via the menu item provided in the Add-Ins tab on your Excel spreadsheet.

How to change the Web Applications root folder:

1. Click on the Add-Ins tab on your Integrated Excel workbook

2. Click the Oracle ADF 11g Desktop Integration Menu

3. Click on the ‘Edit Options’ menu item (see figure below)

The ‘Add-Ins’ tab contains custom ADFDi functionality

ADFDi custom functions

4. You will be presented with a dialog to change the address of the Web Applications root.

Enter the new value of the root that you want. The format will be of the form (see image below):

http://<host_name>:<port>/Application

Editing this option will change the location that your integrated Excel spreadsheet uses as the Web Applications Root folder.

5.3 Importing Data into an Integrated Excel Workbook

End users who use the table component in an integrated excel workbook to upload large amounts of data to a Fusion Web Application can prepare these rows in a non integrated excel workbook. They can then insert the data into the integrated excel workbook before pressing ‘Upload’ to submit their changes.

How to prepare data in a non-integrated Excel workbook:

1. End users arrange the layout of data in a non-integrated Excel worksheet to match the layout of the Table component in the integrated Excel workbook.

For example, if a Table component contains columns such as Product, Price, and Description, reproduce this layout in the non-integrated Excel worksheet by copying the headers from the Integrated Excel workbook into the non integrated Excel workbook.

Select the columns in the integrated excel workbook, press ctrl + C to copy them, go into your non integrated excel workbook, select the left corner cell that you want to begin pasting at, press Ctrl + V to paste the column headers.

Click ‘Add-Ins’Click ‘Oracle ADF 11g Desktop Integration’

Click ‘Edit Options’

2. End users use Excel's functionality to import the rows of data into the non-integrated Excel worksheet in rows under the columns arranged in step 1. Copy the data from the integrated excel workbook and paste it under the columns that you prepared in Step 1.

3. Row values that will be inserted into Table component columns that use the ADF List of Values component must match a choice from the list of values.

How to insert data into the Table component from a non-integrated Excel workbook:

1. In the Table component, end users highlight N existing downloaded rows or new rows at the end of the Table component where N is the number of rows to insert.

2. End users right click and select Insert from Excel’s context menu

3. In the non-integrated Excel worksheet, end users select the cells that they want to insert into the rows of the Table component created in step Error: Reference source not found.

Warning: Select the cells in the non integrated Excel worksheet and not the rows or columns

4. In Excel's menu, click Home > Copy.

5. In the Table component, select the upper left corner cell of the rows inserted in step Error: Reference source not found.

6. Alternatively, select all rows inserted in step Error: Reference source not found.

7. In Excel's menu, click Home > Paste.

8. End users can now invoke the Table component's Upload method to upload the data

6. FAQ / Troubleshooting

6.1 COM Exception HRESULT: 0x800A03EC

6.1.1 Exception Stack Trace: COMException: Exception from HRESULT: 0x800A03ECStack:

Server stack trace: Exception rethrown at [0]: at System.Runtime.Remoting.Proxies.RealProxy.HandleReturnMessage(IMessage reqMsg, IMessage retMsg)at System.Runtime.Remoting.Proxies.RealProxy.PrivateInvoke(MessageData& msgData, Int32 type)at Microsoft.Office.Interop.Excel._Application.set_DisplayDocumentActionTaskPane(Boolean RHS)at oracle.adf.client.windows.excel.runtime.ExcelController.InitializeTaskPane()at oracle.adf.client.windows.excel.runtime.ExcelController.Initialize(ActionsPane actionsPane, Boolean initToolbar)at oracle.adf.client.windows.excel.client.ThisWorkbook.InitializeMode(Object sender)

6.1.2 Circumstances under which issue is observed

i. Issue was observed when a Desktop Integration worksheet is opened

ii. Machine on which DI is being installed is a fresh machine – which means either it is newly imaged or it has never had a Microsoft Office Install before

iii. Desktop Integration version 1403. Later versions of DI are believed to have a fix for this issue

6.1.3 Workaround

The following workarounds have been tested and have been successful (do any one)

1. Open a design time worksheet:

Opening any design time worksheet will help resolve this issue (If you are a DI developer, you are already familiar with a design time worksheet. If you do not know about Design time worksheets, just open the spreadsheet below. You might get excel prompts – ignore all of them, and just let the spreadsheet open). Once you open the spreadsheet, you can close it.

After doing this step you should no longer face the COM Exception - It is believed to initialize the Microsoft 2007 ribbons which seem to be associated with the above Exception

You can obtain a design time worksheet from here (can also be found on this kix page)

2. Another alternative to the design time worksheets is installing a different version of the DI client and then reinstalling your original version.

a. Uninstall your Desktop Integration version. Go to ADD Remove Programs -> Oracle ADF Desktop Integration -> Remove

b. Install a version of DI later than 1403 – typically 1583 or 1608 have worked (should be available on the kix under Drop 8 section)

c. Open a Desktop Integration worksheet. When you open a DI enabled worksheet, you should no longer see the COM exception. You might see an exception similar to “Binding Container Version Mismatch. Expected version “. If you see this error, it is ok, because your server is running a different version of DI than what you have installed.

d. Uninstall the DI version you just installed (1583 or 1608). Go to Add Remove Programs -> Oracle ADF Desktop Integration -> Remove

e. Install your original version of DI 1403

f. Run your spreadsheet. You should not see the COM exception above.

7. References[1] Working with Oracle ADF Desktop Integration Table-type components http://st-doc.us.oracle.com/review/AS11/web.1111/e10139/work_table_comp.htm#CEGHFDDC[2] Setting up your development Environmenthttp://st-doc.us.oracle.com/review/AS11/web.1111/e10139/inst_conf_dev_env.htm#CACFCACD