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 restore server data context when the 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 About Disconnected Workbooks

End users can open an integrated Excel workbook and log on to a Fusion web application from the workbook ribbon command button 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 button 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. Figure 15-1 shows an example of EditPriceList.xlsx with data updates.

Figure 15-1 Updates in a Disconnected Workbook

Updates in a Disconnected Workbook

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

Figure 15-2 Discard Pending Changes Dialog of a Disconnected Workbook

Discard Pending Changes dialog of a Disconnected Workbook

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 I, "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 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 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.7, "Configuring a Worksheet to Download Pre-Insert Data to 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 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:

  1. Open the integrated Excel workbook.

  2. In the Workbook group of the Oracle ADF tab, click Workbook Properties

  3. In the Edit Worksheet Properties dialog, configure values for the ServerContext group 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...

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

  4. Click OK.

Note:

For integrated Excel workbooks that use Parameters and <invokeAction> executable, you may not need to configure RestoreDataContextActionID and CachedServerContexts, if Parameters and <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 ClearAllData and EditOptions described in Table A-17.

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 ClearAllData and EditOptions described in Table A-17 also clears cached list items.

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 ClearAllData is invoked.

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

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, "Inserting Values in ADF Table Columns 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."

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.