13 Testing Your Integrated Excel Workbook

This chapter describes features in ADF Desktop Integration that help you test your integrated Excel workbook as you configure it. It includes the following sections:

Section 13.1, "About Testing Your Integrated Excel Workbook"
Section 13.2, "Testing Your Fusion Web Application"
Section 13.3, "Validating the Integrated Excel Workbook Configuration"
Section 13.4, "Testing Your Integrated Excel Workbook"
Section 13.5, "Running a Server Ping Test"

13.1 About Testing Your Integrated Excel Workbook

Testing an integrated Excel workbook before you publish and deploy it to your end users enables you to verify that the functionality you configure behaves as you intend. Before you test your integrated Excel workbook, test the Fusion web application with which you integrate the Excel workbook.

Before you deploy your integrated Excel workbook, you must validate it and test its integration with your Fusion web application. Testing an integrated Excel workbook includes the following processes:

Validating the integrated Excel workbook
Running the integrated Excel workbook in test mode

13.1.1 Integrated Excel Workbook Testing Use Cases and Examples

To test your integrated Excel Workbook, click the Run button on the Oracle ADF tab, and click the Stop button to return to the design mode. Figure 13-1 shows the buttons of the Oracle ADF tab in design mode and in test mode.

Figure 13-1 Run and Stop buttons in Oracle ADF tab

13.1.2 Additional Functionality of Testing an Integrated Excel Workbook

After you have validated and tested your integrated Excel workbook, you may find that you need to add additional functionality for your workbook. Following are links to other functionalities that you can use:

Publishing your integrated Excel workbook: After you test and validate your workbook, you must publish it. For more information see, Section 14.3, "Publishing Your Integrated Excel Workbook."
Deploying your integrated Excel workbook: After you publish your workbook, you must deploy it with your Fusion web application. For more information, see Section 14.4, "Deploying a Published Workbook with Your Fusion Web Application."
Working in disconnected mode: After downloading data to the integrated Excel workbook, sometimes end users may need to use the workbook when a server connection may not be available. For more information, see Section 15.1, "About Disconnected Workbooks."

13.2 Testing Your Fusion Web Application

Test the Fusion web application that you integrate your Excel workbook with before you start testing the integrated Excel workbook. For information about testing a Fusion web application, see the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. Verify that the Fusion web application you want to integrate an Excel workbook with, supports ADF Desktop Integration by carrying out the procedure described in Section C.1, "Verifying That Your Fusion Web Application Supports ADF Desktop Integration."

Before you run the Fusion web application in JDeveloper, ensure that you have closed all integrated Excel workbooks and the Excel application. The application deployment may fail if it encounters locked files as Excel locks the files that it opens.

Tip:

If you plan to test integrated Excel workbooks that you downloaded from web pages of the Fusion web application, you should republish them before redeploying the application. Republishing the workbooks ensures that you have their latest versions.

If you make changes to the Fusion web application to resolve problems identified by testing the application, you need to:

Close Excel and all integrated Excel workbooks. The application deployment may fail if it encounters locked files, as Excel locks the files that it opens.
Rebuild the JDeveloper project where you develop the Fusion web application.
Run the Fusion web application.
Reload the page definition files that are associated with the integrated Excel workbook. Click the Refresh Bindings button in Oracle ADF tab of the integrated Excel workbook to reload the page definition files.

These steps make sure that the changes in the Fusion web application are available to the integrated Excel workbook. For information about how to reload a page definition file, see Section 4.3.3, "How to Reload a Page Definition File in an Excel Workbook."

13.3 Validating the Integrated Excel Workbook Configuration

ADF Desktop Integration provides a set of validation rules for the integrated Excel workbook configuration. After creating your integrated Excel workbook, you may validate the workbook before you proceed for testing or deployment.

13.3.1 How to Validate the Integrated Excel Workbook Configuration

You should validate the integrated Excel workbook configuration before testing or deploying the workbook.

To validate the integrated Excel workbook configuration:

Open the integrated Excel workbook.
In your integrated Excel workbook, click the Oracle ADF tab.
In the Test group, click Validate.

The Configuration Validation dialog appears listing all your warnings and errors.
If any warning or error is displayed, click to select it. A description of the warning or error message is displayed in the dialog.

For example, Figure 13-2 illustrates a validation failure message of an invalid EL expression.

Figure 13-2 Invalid EL Expression Resulting in a Validation Failure

If no warning or error appears, click Close to close the dialog.

Note:

You may continue to keep the Configuration Validation dialog open while you resolve the validation failures. To verify whether you have resolved an error or a warning, click Revalidate to run the validation rules again.

13.3.2 What Happens When You Validate the Integrated Excel Workbook Configuration

When you validate the workbook at design time, ADF Desktop Integration validates all workbook configuration properties, including worksheet and worksheet component properties, against defined validation rules. Any and all validation failures (errors and warnings) are listed in the Configuration Validation dialog. Each validation failure, when selected, provides contextual information about the failure, and provides enough detail to locate and fix each validation failure.

The Configuration Validation dialog provides the following information for each validation failure:

Severity type (error or warning)
Name of the worksheet. The word Workbook is displayed if the validation failure does not correspond to a particular worksheet.
Worksheet component ID ("Workbook" or "Worksheet" if the validation failure does not correspond to a particular worksheet component)
Property containing the validation failure
Description of the validation failure (error or warning)

When you select a specific failure entry in the dialog, the dialog displays additional details about the failure including:

Full property context path
Property value

Certain validation rules may result in multiple distinct failures. For example, when an expression is being validated, different validation failures occur based on expression type, expression syntax, or the location in which the property is exposed in the workbook configuration.

For example, consider the following expression value:

#{bindings.EmpView1.hints.Empno.label}

The expression value is legal when used within a column header label inside of a table component, but the same expression value is illegal when specified as part of the Worksheet.Title expression.

Note:

If Enabled is set to False for a group of workbook configuration properties, validation of other property values within the same group is skipped.

13.3.3 How to Fix Validation Failures

When you validate your workbook, you might get validation failures or warning messages, which you can fix easily by following these steps:

Identify the component that gave the error or warning message.

In Figure 13-2, note that the ADF Input Text component generated the error. From all Input Text components in the worksheet, identify the component that uses searchTerm2 expression.
Open the property editor of the component.
Navigate to the invalid property value identified by the full property context path.
Edit the property value to resolve the validation failure.

Figure 13-3 illustrates the ADF InputText component property editor and its invalid EL expression.

Figure 13-3 Resolving Validation Failure
Revalidate the workbook to verify whether the validation failure has been resolved. Click Revalidate to run the validation rules again.
After fixing all validation failures, click Close to close the Configuration Validation dialog.

Figure 13-4 illustrates the Configuration Validation dialog with no warnings or error messages.

Figure 13-4 Configuration Validation Dialog with No Validation Failure Messages

13.3.4 How to Log the Integrated Excel Workbook Configuration Validation Failures at Runtime

By default, there is no runtime validation of integrated Excel workbook configuration. However, you may log validation failures at runtime by setting the client log level to Error or Warning. For more information about enabling client-side logging, see Section C.3.2, "About Client-Side Logging."

13.4 Testing Your Integrated Excel Workbook

As you configure your Excel workbook to integrate with a Fusion web application, you can switch to test mode from design mode to test the functionality that you add to the workbook. You use the Oracle ADF tab to switch to test mode from design mode and from design mode to test mode.

Test mode enables you to test the functionality of your integrated Excel workbook as you configure it incrementally. It also enables you to view the integrated Excel workbook from the end user's perspective, as test mode corresponds to what end users see when they view and execute the published integrated Excel workbook. The difference between an integrated Excel workbook in test mode and a published integrated Excel workbook is that the ADF Desktop Integration task pane is not available to users of the published integrated Excel workbook.

For more information about test mode and design mode, see Section 5.1, "About Development Tools."

There are some differences between the test mode and the runtime mode when you run the integrated Excel workbook. Table 13-1 lists these differences.

Table 13-1 Differences between Test mode and Runtime mode

Test mode	Runtime mode
Does not perform tamper check	Performs tamper check
Does not display the connection confirmation dialog	Displays the connection confirmation dialog
Displays the Oracle ADF ribbon tab	Does not display Oracle ADF tab
Allows you to switch back to design mode	Does not allow you to switch back to design mode

ADF Desktop Integration can generate log files that capture information based on events triggered by an integrated Excel workbook. For more information about these log files, see Appendix C, "Troubleshooting an Integrated Excel Workbook."

Note:

Before you start testing the integrated Excel workbook, ensure that:

The Fusion web application is running
The ping to server is successful, and the server is configured for ADF Desktop Integration

To run an integrated Excel workbook in test mode:

To test and run an integrated Excel workbook, click the Run button on the Oracle ADF tab.

The integrated Excel workbook switches to test mode from design mode.

To stop test mode and return the integrated Excel workbook to design mode:

In the integrated Excel workbook that you are testing, click the Stop button on the Oracle ADF tab.

The integrated Excel workbook switches to design mode from test mode.

Note:

When the end user tries to close the integrated Excel workbook, Microsoft Excel prompts a dialog to save the workbook even if the end user has not modified it after opening it. This behavior is expected because ADF Desktop Integration modifies an integrated Excel workbook each time the end user opens it.

13.5 Running a Server Ping Test

The server ping test enables you to check the version of ADF Desktop Integration Remote Servlet in a running system. It also helps to confirm that the remote servlet is loaded and responding.

After running the Fusion web application and logging in as a valid user, open a URL in the following format to verify whether the remote servlet is running:

http://<hostname>:<portnumber>/<context-root>/adfdiRemoteServlet

For example, if you run the Master Price List Fusion web application, open the following URL:

http://127.0.0.1:7101/FODMasterPriceList/adfdiRemoteServlet

The following response verifies that the remote servlet is running:

Oracle ADF 11g Desktop Integration (11.1.1.55.30) [1738]

Response from oracle.adf.desktopintegration.servlet.DIRemoteServlet: OK.

In the above example, the remote servlet version is 11.1.1.55.30 and the ADF Desktop Integration version corresponding to the remote servlet is 1738.

Note:

A valid user session is required to run the server ping test. If authentication is enabled for the web application, you will be prompted for valid credentials to log in.