D Using Workbook Management Tools

This appendix describes how to use the workbook conversion utility and the workbook administration tool. You can use these tools to prepare and manage workbooks that you integrate with a Fusion web application.

This appendix includes the following sections:

Section D.1, "Using the Workbook Conversion Utility"
Section D.2, "Using the Workbook Administration Tool"

D.1 Using the Workbook Conversion Utility

Use the conversion utility to convert an Excel workbook so that you can start configuring the workbook with Oracle ADF functionality. Section 4.4, "Preparing Your Workbook" describes how you run the conversion utility. Note that running conversion utility does not embed Oracle ADF Desktop Integration in Excel file. It prepares the Excel file for integration with ADF web application.

The Oracle ADF Desktop Integration module stores the conversion utility (convert-adfdi-excel-solution.exe) in the following directory:

ADFDI_HOME\bin\excel\convert

where ADFDI_HOME refers to the directory in which you set up the Oracle ADF Desktop Integration module as described in Section 3.8, "Using the Oracle ADF Desktop Integration Module on a System with Multiple Instances of JDeveloper".

Table D-1 describes the arguments that the conversion utility supports.

Table D-1 Workbook Conversion Utility Command-line Arguments

Use this argument...	To...
`-attach`	Attach properties to an Excel workbook so that you can configure it to use Oracle ADF functionality. Example usage: `convert-adfdi-excel-solution.exe MyWorkbook.xlsx -attach`
`-detach`	Remove design time, test mode, and runtime Oracle ADF functionality from an integrated Excel workbook. Use this argument if you want to send an integrated Excel workbook to a user who does not have the Oracle ADF Desktop Integration client framework installed. This allows the user to open the integrated Excel workbook without receiving an error message. Example usage: `convert-adfdi-excel-solution.exe MyWorkbook.xlsx -detach`
`-mode`	Use this argument to change the mode of an integrated Excel workbook from its current mode to design mode, test mode, or runtime mode. Use the `-mode` argument in conjunction with one of the following three arguments to change to the desired mode: `DT` Changes the workbook to design mode. `RT` Changes the workbook to runtime mode. `TST` Changes the workbook to test mode. The following example converts a workbook to design mode: `convert-adfdi-excel-solution.exe MyWorkbook.xlsx -mode DT` Use the `-mode` argument with caution and be aware that the functionality that it provides is not equivalent to the functionality provided by the Oracle ADF Desktop Integration Designer toolbar. For example, if you change to runtime mode (using `-mode RT`), the clean up steps that occur when you use the Oracle ADF Desktop Integration Designer toolbar menu button do not occur. Similarly, if you use it to switch to design mode (`-mode DT`), placeholder text that was present prior to publication is not reintroduced.
`-root`	Modify the value of a workbook's `WebAppRoot` property. This argument may be useful where you want to change the `WebAppRoot` property of multiple workbooks through a command-line script. Example usage: `convert-adfdi-excel-solution.exe MyWorkbook.xlsx -root http://myhost:7101/MyApp` The recommended method of changing a workbook's `WebAppRoot` property is through the property inspector for workbook properties in design mode or through the Edit Options dialog box when you switch a workbook to test mode.
`-view`	Use this argument to determine if a workbook has been converted for integration with Oracle ADF and, if so, identify the solution ID and customization version. Example usage: `convert-adfdi-excel-solution.exe MyWorkbook.xlsx -view`
`-wipe`	Remove the value of the `WebAppRoot` workbook property and the mode (design, test, or runtime) from a workbook that is integrated with Oracle ADF. When used in conjunction with the `detach` argument, this argument can be used to return a workbook to a known state. Example usage: `convert-adfdi-excel-solution.exe MyWorkbook.xlsx -wipe`
`-help`	Displays help information about the command-line arguments that the workbook conversion utility supports.

D.1.1 Configuring JDeveloper To Run Workbook Conversion Utility

You can configure JDeveloper to run the conversion utility and avoid command line executions.

To run workbook conversion utility from JDeveloper

Open JDeveloper
From the Tools menu, select External Tools.
In External Tools dialog box, click New. The Create External Tools wizard appears.
In the Type page of wizard, select the Tool Type as External Program.
In External Program Options page of wizard, set the field values as following:
- In Program Executable field, click Browse and select the conversion utility (convert-adfdi-excel-solution.exe) file. The file is available in the following directory:
  
  ADFDI_HOME\bin\excel\convert
- In Arguments field, enter the following as the argument:
```
"${file.path}" -attach
```
- Ensure that directory location in Run Directory is same as Program Executable field.
In the Display page of the wizard, leave the values as default. You may change the Caption to Conversion Utility.
In the Integration page of the wizard, select Navigator Context Menu checkbox.
In the Availability page of the wizard, you can configure JDeveloper to run the tool for Excel workbooks only. Select When Specific File Types are Selected option and move Excel Workbook from Available Types to Selected Types.
Click Finish to close the wizard.
The tool appears in the External Tools dialog box. Click OK to close the dialog.
In Application Navigator, select the Excel file which you want to convert. With file selected, from the Tools menu, select Conversion Utility.

D.2 Using the Workbook Administration Tool

Use the workbook administration tool to set values for a number of workbook properties, such as WebAppRoot, after you publish the finalized integrated Excel workbook. Use this tool if, for example, the URL of your Fusion web application changes after you publish the integrated Excel workbook.

You can also use it when you want to change workbook settings but cannot or do not want to set values for the HTTP filter as described in Section E.2, "Configuring the ADF Desktop Integration Excel Download Filter".

The workbook administration tool is a Java-based program that can be executed on operating systems that support the version of Java used by Oracle ADF. It also requires access to the adf-desktop-integration-admin-tool.jar file which is located in the following directory:

ADFDI_HOME\lib

where ADFDI_HOME is the folder in which you set up the Oracle ADF Desktop Integration module as described in Section 3.8, "Using the Oracle ADF Desktop Integration Module on a System with Multiple Instances of JDeveloper".

The other requirements for components or utilities in the Oracle ADF Desktop Integration module, as outlined in Chapter 3, "Setting Up Your Development Environment", do not apply to the workbook administration tool.

To change workbook settings using the workbook administration tool:

Open a comma nd window and execute the following command:

java -cp adf-desktop-integration-admin-tool.jar oracle.adf.desktopintegration.admintool.WorkbookAdminTool <arg(s)>

where <arg(s)> is one or more of the required or optional arguments that are described in Table D-2.

Table D-2 Command-line Options for the Workbook Administration Tool

Provide a value for this argument...	To...	Is a value for this argument required?
`-workbook`	Specify the directory path to the workbook to update.	Yes
`-root`	Set the value for this property to the fully qualified URL for the web application that you want to integrate your desktop application with.	No
`-mode`	Change the workbook mode to one of the following: `RT` where `RT` specifies runtime mode. `DT` where `DT` specifies design mode. `TST` where `TST` specifies test mode. For more information about workbook modes, see Section 5.1, "Introduction to the Development Tools".	No
`-out`	Specify the directory path and file name for the output file.	Yes
`-quiet`	Specify this argument if you do not want to generate verbose output.	No
`-help`	Print help information.	No

The following command creates a copy of the workbook (text.xlsx) in runtime mode (RT) for a Fusion web application (http://hostname:7101/FODADFBC) and writes it to a directory with a new file name (myresult.xlsx):

java -cp adf-desktop-integration-admin-tool.jar oracle.adf.desktopintegration.admintool.WorkbookAdminTool -workbook test.xlsx -mode RT -root http://hostname:7101/FODADFBC -out myresult.xlsx