15 Using an Integrated Excel Workbook Across Multiple Web Sessions and in Disconnected Mode

This chapter describes the functionality that your end users can use when they are not connected to a Fusion web application. It also describes how to reestablish server data context when an end user connects to a Fusion web application through an integrated Excel workbook after having previously been disconnected from the application.

This chapter includes the following sections:

15.1 Introduction to Disconnected Workbooks

End users can open an integrated Excel workbook and log on to a Fusion web application from the workbook menu that you configure. The Fusion web application assigns a session to the user. Once 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 menu 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 menu, 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.

Functionality Available to End Users in an Integrated Excel Workbook When Disconnected from a Fusion Web Application

When end users are disconnected from the Fusion web application, they 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

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. The following table describes the types of data that an integrated Excel workbook caches. It also describes when the integrated Excel workbook refreshes the data.

This type of data... Is cached when... And refreshed when...
Page definition metadata 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 metadata exists. The page definition metadata is not refreshed unless you download a new copy of the integrated Excel workbook or invoke the workbook actions ClearAllData and EditOptions described in Table A-16.
ADF Desktop Integration List of Values component list items The ADF Desktop Integration 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 ClearAllData and EditOptions described in Table A-16 also clears cached list items.

Resource bundle strings The integrated Excel workbook is first accessed. 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 ClearAllData and EditOptions described in Table A-16.

15.2 Deferring Login for an Integrated Excel Workbook

You can configure an integrated Excel workbook so that an end user can open it and use it without having to log on immediately to the Fusion web application. To do this, you configure the workbook so that no action is invoked which requires a session. Actions that require a session can be grouped into explicit and implicit actions. Explicit actions are those that require a user to click a button or a menu item before it can be invoked. Implicit actions are those configured to be invoked by worksheet events, such as Startup and Activate, or other events that require a server connection (for example, the retrieval of a resource bundle). Once an action that requires a session to proceed is invoked, the end user is prompted to log on to the Fusion web application.

15.3 Reestablishing Server Data Context Between Sessions

You need to configure the page definition file so that the correct view object state is reestablished if the Fusion web application assigns an end user a new session after one of the following events occurs:

  • An 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 Download and Upload actions (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 an 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, there will not be a record to save to if the end user clicks the Save button after the Fusion web application assigns a new session. To prevent this scenario occuring, 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.6, "Configuring a Worksheet to Download Pre-Insert Data to an ADF Table Component".

15.3.1 How to Configure an Integrated Excel Workbook to Reestablish 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 allows you to specify the action binding that uses the attribute binding data to reestablish 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-18.

To configure an integrated Excel workbook to reestablish server data context:

  1. In the integrated Excel workbook, click Worksheet Properties.

  2. In the property inspector that appears, configure values for the ServerContext group of properties as described by the following table.

    For this property... Enter or select this value...
    CacheDataContexts Add an element to the collection of CacheDataContexts. Configure the element you add as follows:
    • RestoreDataContextActionID

      Specify the action binding (for example, the Execute action binding) that connects to the Fusion web application to restore the data specified by CachedServerContexts.

    • CachedServerContexts

      An array that identifies the attribute binding values to cache and set before the action binding specified by RestoreDataContextActionID is invoked. Each element in the array (CachedServerContext) supports the CachedAttributeID and RestoredAttributeID properties.

    For more information about the CacheDataContexts property and its subproperties, see Section A.12, "Worksheet Properties".

    IDAttributeID 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 reestablished.

    For more information about this property and its subproperties, see Section A.12, "Worksheet Properties"


  3. Click OK.

15.3.2 What Happens at Runtime When an Integrated Excel Workbook Reestablishes 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.4 Caching Lists of Values for Use in Disconnected Mode

The Oracle ADF Desktop Integration module caches the values referenced by the ADF Desktop Integration List of Values and the ADF Desktop Integration Tree Node List components 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 an end user selects a value at runtime. For more information about using these components to create lists of values, see the following sections:

The Oracle ADF Desktop Integration module 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, the Oracle ADF Desktop Integration module 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, "Inserting Values in an ADF Table Component from a Web Page Pick Dialog".

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