15 Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode
This chapter describes how to configure the integrated Excel workbook so that your use cases work properly across multiple web application sessions.
This chapter includes the following sections:
15.1 About Disconnected Workbooks
End users can open an integrated Excel workbook and log on to a Fusion web application from the workbook ribbon command that you configure. The Fusion web application assigns a session to the user. After a connection to the Fusion web application is established and a valid session assigned, end users can download data from the Fusion web application to the workbook. They can then log off from the Fusion web application using the workbook ribbon command or otherwise disconnect from the Fusion web application by, for example, disconnecting from the network that hosts the Fusion web application.
How the Fusion web application terminates the session assigned to the user depends on how the user disconnects from the Fusion web application. If the user logs off from the Fusion web application using a workbook command, the Fusion web application terminates the session immediately. If the user disconnects from the Fusion web application by some other means (for example, closing the workbook), the Fusion web application terminates the session assigned to the user after session timeout expires.
Using integrated Excel workbooks disconnected from the Fusion web application, end users can perform the following actions:
Modify data downloaded from the Fusion web application
Insert new data into the appropriate ADF Table component contained in the workbook
Save changes to data and close and reopen the workbook without having to upload data to the Fusion web application
Track and update changes in the ADF Table component
15.1.1 Disconnected Workbooks Use Cases and Examples
When end users open a published integrated Excel workbook, the workbook downloads required data. Then, if they disconnect from the server, they can continue to edit and update the data in the integrated Excel workbook, and save and close it.
The integrated Excel workbook, when opened after saving, detects the updates and prompts the end user to discard the changes, as shown in Figure 15-1. If the end user clicks No, the changes would appear in the workbook. If the end user clicks Yes, the integrated Excel workbook prompts to connect to the server to download data.
15.1.2 Additional Functionality for Disconnected Workbooks
After you have validated and tested your integrated Excel workbook in disconnected mode, you may find that you need to add additional functionality for your workbook. Following are links to other functionalities that you can use:
Troubleshooting integrated Excel workbook: You might encounter some problems while developing or deploying an integrated Excel workbook. For more information, see Appendix C, "Troubleshooting an Integrated Excel Workbook."
Installing runtime edition of ADF Desktop Integration: You must install the runtime edition of ADF Desktop Integration to enable end users to use ADF Desktop Integration and integrated Excel workbooks. For more information, see Appendix H, "End User Actions."
15.2 Restore Server Data Context Between Sessions
You must configure the page definition file so that the correct view object state is restored if the Fusion web application assigns the end user a new session after one of the following events occurs:
The end user makes changes to data in a workbook, saves and closes the workbook, reopens the workbook at a later time, and attempts to upload the changes he or she made before saving and closing the workbook.
The time between invocation of an ADF Table component's
Uploadactions (or some other ADF Table component action that contacts the Fusion web application) exceeds the session timeout value specified for a Fusion web application session.
Both the scenarios described in the previous list involve two sessions. The first session is assigned when the end user opens an integrated Excel workbook and logs on to the Fusion web application. The Fusion web application terminates this session when the end user logs off from the Fusion web application or when the session expires. The Fusion web application assigns a second session when the end user reopens the integrated Excel workbook or invokes an action that interacts with the Fusion web application.
In addition to configuring the page definition file, configure the functionality in an integrated Excel workbook so that pending changes are not lost if the end user logs off from the Fusion web application or a session expires before changes are committed to the Fusion web application. For example, you configure the worksheet
Startup event to invoke a
CreateInsert action binding and a worksheet
DownSync action. You also configure an ADF Button component labeled Save to invoke the worksheet
UpSync action and the
Commit action binding. If the end user's session ends, no record is saved even if the end user clicks the Save button after the Fusion web application assigns a new session. To prevent this scenario occurring, it is better to invoke the
CreateInsert action binding from the ADF Button component labeled Save.
Another example is the behavior of the ADF Table component's
DownloadForInsert action. If you create a custom method in the Fusion web application that creates temporary records to support the invocation by the ADF Table component of the
DownloadForInsert action, make sure to remove these temporary records after successful invocation of the
DownloadForInsert action. For more information about the use of the
DownloadForInsert action, see Section 7.5, "Configuring a Worksheet to Download Data as Pending Insert Rows in an ADF Table component."
15.2.1 How to Configure an Integrated Excel Workbook to Restore Server Data Context
You specify the attribute bindings that you want to cache in an integrated Excel workbook between sessions as values for the worksheet's
ServerContext group of properties. This group of properties also enables you to specify the action binding that uses the cached attribute binding data to restore server-side context when a Fusion web application assigns a new session to the integrated Excel workbook.
Before you can specify values for the
ServerContext group of properties, the page definition file that is associated with the worksheet must expose the attribute bindings and action bindings for which you want to restore server context. For information about adding attribute bindings and action bindings to a page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook." For information about the
ServerContext group of properties, see the entry for
ServerContext in Table A-19.
Before you begin:
It may be helpful to have an understanding of how to restore server data context. For more information, see Section 15.2, "Restore Server Data Context Between Sessions."
You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 15.1.2, "Additional Functionality for Disconnected Workbooks."
To configure an integrated Excel workbook to restore server data context:
Open the integrated Excel workbook.
In the Workbook group of the Oracle ADF tab, click Worksheet Properties.
In the Edit Worksheet Properties dialog, configure values for the
ServerContextgroup of properties as described by Table 15-1.
Table 15-1 ServerContext Properties to Restore Server Data Context
For this property... Enter or select this value...
Add an element to the collection of
CacheDataContexts. Configure the element you add as follows:
Specify the action binding (for example, the
Executeaction binding) that connects to the Fusion web application to restore the data specified by
An array that identifies the attribute binding values to cache and set before the action binding specified by
RestoreDataContextActionIDis invoked. Each element in the array (
CachedServerContext) supports the
For more information about the
CacheDataContextsproperty and its subproperties, see Section A.13, "Worksheet Properties."
Specify the attribute binding that uniquely identifies the row displayed in the current worksheet. At runtime, the value that this property references is used to determine if the server data context has been correctly restored.
For more information about this property and its subproperties, see Section A.13, "Worksheet Properties."
If your integrated Excel workbook uses parameters and you have deployed it by downloading it from your Fusion web application, see Section 14.5.3, "How to Configure Parameters Properties in the Integrated Excel Workbook."
For integrated Excel workbooks that use
<invokeAction> executable, you may not need to configure
<invokeAction> can restore server data context when a new session is created.
15.2.2 What Happens at Runtime: How the Integrated Excel Workbook Restores Server Data Context
During the session that is assigned the initial session (for example,
session ID 1), the worksheet caches data using the
ServerContext group of properties. In a later session with a different session ID (for example,
session ID 2), where the ADF Table component's
Upload action is invoked, the data cached in the
ServerContext group of properties is sent to the Fusion web application.
15.3 Caching of Static Information in an Integrated Excel Workbook
Certain types of relatively static data are cached in the integrated Excel workbook to allow end users to use the workbook while disconnected from the Fusion web application. Table 15-2 describes the types of data that an integrated Excel workbook caches. It also describes when the integrated Excel workbook refreshes the data.
Table 15-2 Types of Data an Integrated Excel Workbook Caches
|This type of data...||Is cached when...||And refreshed when...|
Page definition configuration that is not runtime specific such as control binding types, IDs, and labels.
An integrated Excel worksheet bound to a page definition file is activated and no cache of the page definition file's configuration exists.
The page definition configuration is not refreshed unless you download a new copy of the integrated Excel workbook or invoke the workbook actions
ADF List of Values component list items
The ADF List of Values component first downloads the list items from the Fusion web application.
The values of the list items hosted by the Fusion web application differ from those cached by the integrated Excel workbook. The cached list items are refreshed only once per workbook session and only if a workbook session exists.
Invoking the workbook actions
Resource bundle strings
The integrated Excel workbook is first initialized. A workbook is initialized when it is opened for the first time after conversion, or after
The cache of resource bundle strings is not refreshed unless you download a new copy of the integrated Excel workbook or invoke the workbook actions
15.4 Caching Lists of Values for Use in Disconnected Mode
ADF Desktop Integration caches the values referenced by the ADF List of Values and the TreeNodeList subcomponents that you use to create lists of values and dependent lists of values so that these components do not send a request to the Fusion web application when the end user selects a value at runtime. For more information about using these components to create lists of values, see the following sections:
ADF Desktop Integration caches up to two hundred and fifty values for each component. If a component references a list of values with more than two hundred and fifty values, ADF Desktop Integration caches the first two hundred and fifty values and writes a warning message to the client-side log file for subsequent values. Consider configuring your integrated Excel workbook to invoke a pick dialog from a page in your Fusion web application where a list of values references more than two hundred and fifty values. For more information about client-side log files, see Section C.3, "Generating Log Files for an Integrated Excel Workbook." For more information about invoking a pick dialog from a Fusion web application page, see Section 8.4, "Displaying Web Pages from a Fusion Web Application" and Section 8.5, "Adding a Custom Popup Picker Dialog to an ADF Table Column."
Cached list of values in an integrated Excel workbook get refreshed once per workbook session. This refresh occurs after the user reestablishes a web session with the Fusion web application and if the values referenced by the Fusion web application have changed since the integrated Excel workbook last cached the list of values.
The upload of a selected value from a list of values causes the upload to fail if the selected value no longer exists in the Fusion web application. This may occur if, for example, one end user deletes the value in the Fusion web application while another end user modifies the selected value in the cached list of values of an integrated Excel workbook and attempts to upload the modified value to the Fusion web application. For more information about handling data conflict, see Section 12.7, "Handling Data Conflicts When Uploading Data from a Workbook."
Note that if you change the Fusion web application configuration after you have deployed the Fusion web application and the end users have started using the published integrated Excel workbooks, you must inform the end users to download a fresh copy of the integrated Excel workbook, or run the
ClearAllData command. For more information about the
ClearAllData action, see Table A-17
The changes in your Fusion web application might include changing the definitions of the list bindings associated with the ADF List of Values and TreeNodeList subcomponents exposed in the worksheet. Changing list binding configuration can cause unexpected exceptions in workbooks that have been downloaded and run prior to the change.