14 Deploying Your Integrated Excel Workbook

This chapter describes how to publish and deploy a workbook integrated with a Fusion web application to end users, and how to pass parameters from the Fusion web application to the integrated Excel workbook.

This chapter includes the following sections:

14.1 About Deploying Your Integrated Excel Workbook

After you finish development of your integrated Excel workbook, you make the final integrated Excel workbook available to end users by deploying the resulting Fusion web application to an application server. Before you deploy a finalized Excel workbook that integrates with the Fusion web application, you must publish it as described in Section 14.3, "Publishing Your Integrated Excel Workbook." After you have published the Excel workbook, you can deploy it using one of the methods outlined in the "Deploying Fusion Web Applications" chapter of the Developing Fusion Web Applications with Oracle Application Development Framework.

The end users that you deploy an integrated Excel workbook to must do the following:

When you deploy your integrated Excel workbook with your Fusion web application, you are not required to provide the download URL of workbooks explicitly. The end users can download the integrated Excel workbooks from the Fusion web application's user interface. For more information, see Section 14.4, "Deploying a Published Workbook with Your Fusion Web Application."

14.1.1 Integrated Excel Workbook Deployment Use Cases and Examples

You use the Publish button of the Oracle ADF tab to save a copy of the workbook, which is ready for publishing. Figure 14-1 shows the Publish button and the Publish Workbook dialog that opens when you click the Publish button to save a copy of the integrated Excel workbook ready to be published and deployed with the Fusion web application.

Figure 14-1 Publish Workbook Dialog

This image is described in the surrounding text

14.1.2 Additional Functionality for Deploying Your Integrated Excel Workbook

After you have published and deployed 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:

14.2 Making ADF Desktop Integration Available to End Users

End users who want to use the functionality that you configure in an integrated Excel workbook must install the Runtime edition of ADF Desktop Integration. The installation program (setup.exe) is located in the adfdi-excel-runtime-client-installer.zip file available in MW_HOME\oracle_common\modules\oracle.adf.desktopintegration_12.1.3 directory, where MW_HOME is the Middleware Home directory.

For information about using the installation program, see the "Making the Runtime Edition of ADF Desktop Integration Available to Multiple End Users" section in Administering Oracle ADF Applications.

14.3 Publishing Your Integrated Excel Workbook

After you finish configuring the Excel workbook with Oracle ADF functionality, you must publish it. Publishing a workbook makes it available to the end users for whom you configured the integrated Excel workbook.

ADF Desktop Integration also provides you with two methods to publish your workbook. You can publish your integrated Excel workbook directly from Excel, or you can use the publish tool available in JDeveloper to publish the workbook from the command line. The command-line publish tool enables you to use ANT build scripts to publish an integrated Excel workbook from your Fusion web application.

Notes:

  • After publishing one or more workbooks, you should restart the Fusion web application in order for those workbooks to be downloaded and opened successfully in Microsoft Excel. If the web application is not restarted, you might get errors, such as the following:

    TampercheckErrorException: ADFDI-05537: The integrity of the workbook integration could not be determined.

  • Customization-enabled workbooks can only be published to a target location that is under the public_html directory (or its sub-directories) of the associated project.

14.3.1 How to Publish an Integrated Excel Workbook from Excel

You publish a workbook by clicking a button on the Oracle ADF tab and specifying values in the dialogs that appear, or by using the command-line publish tool. You can use the command line publish tool to publish a workbook from your Fusion web application.

Before you begin:

It may be helpful to have an understanding about how to publish your integrated Excel workbook. For more information, see Section 14.3, "Publishing Your Integrated Excel Workbook."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook."

To publish a workbook from Excel:

  1. Open the integrated Excel workbook.

  2. Ensure that the ApplicationHomeFolder and WebPagesFolder properties in the Edit Workbook Properties dialog are correct. If these properties are not set, ADF Desktop Integration prompts to set them when you publish the integrated Excel workbook.

    For more information, see Section 4.2.2, "How to Configure a New Integrated Excel Workbook."

  3. In the Oracle ADF tab, click the Publish button.

  4. Specify the directory and file name for the published workbook in the Publish Workbook dialog that appears, as shown in Figure 14-1. The directory and file name that you specify for the published workbook must be different from the directory and file name for the design time workbook.

  5. Click Save to save changes.

14.3.2 How to Publish an Integrated Excel Workbook Using the Command Line Publish Tool

The publish tool is run from the command line, and is available in the MW_HOME\jdeveloper\adfdi\bin\excel\tools\publish directory as publish-workbook.exe. Before you run the publish tool, open the source integrated Excel workbook and ensure that the ApplicationHomeFolder and WebPagesFolder properties in the Edit Workbook Properties dialog are correct.

Note:

You cannot publish a workbook that is already published, or is in runtime mode.

Before you begin:

It may be helpful to have an understanding about how to publish your integrated Excel workbook. For more information, see Section 14.3, "Publishing Your Integrated Excel Workbook."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook."

Now, navigate to MW_HOME\jdeveloper\adfdi\bin\excel\tools\publish directory and run the publish tool using the following syntax:

publish-workbook -workbook (-w) <source-workbook-path> -out (-o) <destination-workbook-path>

where source-workbook-path is the full path of the source workbook, and destination-workbook-path is the full path where the published workbook is saved.

For example:

publish-workbook -workbook D:\Application1\Project1\ViewController\src\oracle\sampledemo\excel\workbook-src.xlsx -out D:\Application1\Project1\ViewController\public_html\excel\published\workbook.xlsx

Tip:

For more information about the arguments required by the publish tool, run the following command:

publish-workbook -help (-h)

Notes:

  • Always specify the absolute paths of the source and destination workbooks. The publish tool does not support relative paths of the workbooks.

  • The destination workbook cannot have the same name as the source, even if the workbook paths are different.

After publishing the integrated Excel workbook successfully, the publish tool displays a success message. If there is any error while publishing the workbook, the publish tool aborts the process and the error messages are displayed on the command line console.

If you are using the command line publish tool, note that by default the publish tool logs messages to the command line console at information level.

Using the Publish Tool with ANT

You can create ANT scripts to run the publish tool from JDeveloper when you build your Fusion web application. You can use either of the following methods to run the utility using ANT:

  • Generate an ANT build script for the project and add a target to run the workbook command line publish tool

  • Generate or create a separate ANT build script for running the workbook command line publish tool

A sample ANT build script (publish-workbook.xml) to run the publish tool is available in the MW_HOME\jdeveloper\adfdi\bin\excel\samples directory. The sample ANT script demonstrates the invocation of the command-line workbook publishing tool.

14.3.3 What Happens When You Publish an Integrated Excel Workbook

When you click the Publish button in design mode, ADF Desktop Integration performs the following actions:

  1. Validates the mandatory workbook settings.

  2. Updates the client registry. For more information, see Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata."

  3. Creates the published workbook with the specified file name in the specified directory.

    Publish also exports the workbook definition. The published workbook definition XML file is saved at the same location as the design-time copy of the workbook. For more information about workbook definition, see Section 5.15, "Exporting and Importing Excel Workbook Integration Metadata."

  4. Clears the ApplicationHomeFolder, WebAppRoot, and WebPagesFolder properties from the workbook settings of the published workbook.

  5. Removes binding expressions that are visible in the worksheet while the workbook is in design mode.

  6. Changes the mode of the workbook to runtime mode.

  7. Inserts a Publishing Timestamp property into the workbook. This property is visible in the Properties tab of About dialog.

14.4 Deploying a Published Workbook with Your Fusion Web Application

Add the integrated Excel workbook to the JDeveloper project for your Fusion web application if it is not packaged with the other files that constitute your JDeveloper project. This makes sure that the Excel workbooks you integrate with your Fusion web application get deployed when you deploy your finalized Fusion web application. For example, the Summit sample application for ADF Desktop Integration stores the deployed Excel workbooks that it integrates at the following location:

<Summit_HOME>\ViewController\public_html\excel

where Summit_HOME is the installation directory for the Summit sample application for ADF Desktop Integration.

After you decide on a location to store your integrated Excel workbooks, you can configure web pages in your Fusion web application allowing end users to access the integrated Excel workbooks. For example, Figure 14-2 shows Internet Explorer's File Download dialog, which was invoked by clicking the Available Demos > Editable Table Sample menu option on the index.jspx page of the Summit sample application for ADF Desktop Integration.

Figure 14-2 Invoking an Integrated Excel Workbook from a Fusion Web Application

This image is described in the surrounding text

To enable the functionality illustrated in Figure 14-2, the HTTP filter parameters for your Fusion web application must be configured to recognize Excel workbooks. JDeveloper automatically configures these parameters for you when ADF Desktop Integration is enabled in the Fusion web application. If you want to manually configure the HTTP filter parameters, see Appendix D, "ADF Desktop Integration Settings in the Web Application Deployment Descriptor."

After you have configured the HTTP filter for your Fusion web application, you configure the web pages that the Fusion web application displays to end users to allow them to invoke Excel workbooks. A basic method of invoking an Excel workbook that you have integrated with a Fusion web application is to provide a hyperlink that invokes the workbook. For example, you could write the following ADF code in a web page:

<af:link text="Editable Table Sample" destination="/excel/EditCustomers.xlsx"/>

where excel is a subdirectory of the directory specified by the WebPagesFolder workbook property and EditCustomers.xlsx is the Excel workbook that the end user invokes.

You can provide functionality that allows end users to invoke Excel workbooks from buttons, lists, and ribbon commands. The following list provides some examples:

  • Button

    Display a button on the web page that, when clicked, invokes the integrated Excel workbook.

  • Selection list

    Use the ADF Faces selectOneChoice component with a button to invoke an integrated Excel workbook.

  • Menu

    Use the ADF Faces goMenuItem component.

    The Available Demos menu, as illustrated in Figure 14-2, uses the goMenuItem component. The following entry appears in the index.jspx page of the Summit sample application for ADF Desktop Integration and demonstrates the goMenuItem component:

    <af:goMenuItem text="Editable Table Sample" id="gmi1"
  destination="/excel/EditCustomers.xlsx"/>

For more information about creating web pages for a Fusion web application, see the Developing Web User Interfaces with Oracle ADF Faces.

14.4.1 What Happens at Runtime: Deploying a Published Workbook

When web.xml is configured for a Fusion web application that uses ADF Desktop Integration, the following happens:

  • The DIExcelDownloadFilter filter is defined.

  • Filter mappings are defined for *.xlsx and *.xlsm files.

When the end user makes an http request for a workbook (for example, user clicks a link in a web page from the application), the DIExcelDownloadFilter filter embeds the WebAppRoot property into the workbook as it gets streamed back as the http response. The WebAppRoot property is later used by the ADF Desktop Integration client to connect to the Fusion web application, establish a user session, and send data back and forth.

The DIExcelDownloadFilter filter constructs the WebAppRoot value from the current HttpServletRequest object that is passed in to the doFilter() entry point. The filter code calls HttpServletRequest.getRequestURL()and gets the "root" portion of the full URL by removing everything after the context path portion (uses HttpServletRequest.getContextPath()).

14.5 Passing Parameter Values from a Fusion Web Application Page to a Workbook

A Fusion web application page can be configured to pass parameter values to an integrated Excel workbook when the end user downloads the workbook from the page. The workbook parameter values can be used as arguments to ADFm methods (among other uses). For example, consider a page that displays a table of customers, but filtered for a particular city specified by the end user. The City ID provided by the end user is used as an argument to a custom method that alters the View Object's query to return customers with a matching City ID. Such a page could also allow the end user to download an integrated workbook that will display the same customer table with data automatically filtered for the city currently selected on the page. As the integrated workbook is downloaded, the City ID is embedded in it as a workbook parameter value.

To pass parameters from the Fusion web application page to the integrated Excel workbook, follow these steps:

  1. Verify that the HTTP filter is configured to allow end users to download integrated Excel workbooks from the Fusion web application. By default, JDeveloper configures the HTTP filter with appropriate values when you enable ADF Desktop Integration in a project. To verify the parameter values of the HTTP filter, see Section D.2, "Configuring the ADF Desktop Integration Excel Download Filter."

  2. Use Name/Value pairs as URL arguments in the web page of Fusion web application that allows end user to download the workbook. For more information, see Section 14.5.1, "How to Configure the Fusion Web Application's Page to Pass Parameters."

  3. Define the parameter name in the Edit Workbook Properties dialog and in the Edit Worksheet Properties dialog. For more information, see Section 14.5.2, "How to Configure Parameters Properties in the Integrated Excel Workbook."

  4. Configure the page definition file associated with the worksheet in the integrated Excel workbook by adding <parameter> elements. For more information, see Section 14.5.3, "How to Configure the Page Definition File for the Worksheet to Receive Parameters."

Figure 14-3 illustrates the steps to pass parameter from the Fusion web application to the integrated Excel workbook.

Figure 14-3 Configuring Workbook and Fusion Web Application to Pass Parameters

This image is described in the surrounding text

14.5.1 How to Configure the Fusion Web Application's Page to Pass Parameters

A component, such as <af:link>, can be used to allow end users to download a published copy of an integrated workbook. The component's destination URL would reference the integrated workbook, and in its query portion, the URL parameter names and values correspond to the workbook's parameter names and values. You also specify the commands on the page that, when invoked, require the Fusion web application to refresh the values referenced by the component and its property values.

For more information about downloading files using action components, see the "How to Use an Action Component to Download Files" section in Developing Web User Interfaces with Oracle ADF Faces.

Before you begin:

It may be helpful to have an understanding of how to pass parameter values from the Fusion web application to the integrated Excel workbook. For more information, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook."

To configure the page in the Fusion web application:

  1. In JDeveloper, insert the component or tag (such as af:link ) into the page from which the end user downloads the integrated Excel workbook.

  2. In the Structure window, right-click the component and choose Go to Properties.

  3. Expand the Common section and set values for the properties.

    Table 14-1 describes the properties of af:link component.

    Table 14-1 Properties for af:link Tag

    Property Value

    Text

    Write the text that appears to end users at runtime.

    For example, write text such as the following to appear at runtime:

    Download to Excel

    Destination

    Invoke the expression builder to write an EL expression that specifies the integrated Excel workbook and the values to download as a URL argument:

    For example, write an EL expression such as the following:

    "/excel/EditableCustomerSearchParam.xlsx?CityID=#{bindings.CityID.attributeValue}"

    Note that the runtime URL-encoded value of the entire query string to the right of ? must be less than 2048 bytes. If the runtime value exceeds 2048 bytes, the integrated Excel workbook will contain only the URL arguments that fit in 2048 bytes. Subsequent URL arguments do not get included with the integrated Excel workbook. Instead, the Fusion web application writes log entries for these URL arguments identifying them as having not been included.

    For example, the total size of the result when the following EL expression is evaluated and then URL-encoded must be less than 2048 bytes.

    CityID=#{bindings.CityID.attributeValue}&CityCtgType=#{bindings.CityCtgType.attributeValue}.

    Also note that if the URL contains more than 256 characters, an exception is raised when the end user downloads and opens the integrated Excel workbook without saving it. To resolve this problem, you must limit your URL length to 256 characters, or instruct the end user to save the workbook before opening it.

  4. Optionally, expand the Behavior section and specify component IDs for the partialTriggers property that, when invoked, update the values of the af:link tag and its Destination property.

    For example, if you have navigation buttons with the IDs NextButton, PreviousButton, FirstButton, and LastButton, specify them as follows:

    :NextButton :PreviousButton :FirstButton :LastButton

  5. Save the page.

    The following example shows the entries that JDeveloper generates in a JSF page using the examples in this procedure:

    <af:link text="Download to Excel"
destination="/excel/EditableCustomerSearchParam.xlsx?CityID=#{bindings.CityID.attributeValue}"
partialTriggers=":NextButton :PreviousButton :FirstButton :LastButton"/>

14.5.2 How to Configure Parameters Properties in the Integrated Excel Workbook

You configure the workbook Parameters property and the worksheet Parameters property so that the integrated Excel workbook that the end user downloads from the Fusion web application receives parameter values included in the query string of the workbook download URL.

Before you begin:

It may be helpful to have an understanding of how to pass parameter values from the Fusion web application to the integrated Excel workbook. For more information, see Section 14.5, "Passing Parameter Values from a Fusion Web Application Page to a Workbook."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook."

To configure the workbook Parameters property:

  1. Open the integrated Excel workbook.

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

  3. Click the browse (...) icon beside the input field for Parameters to invoke the Edit Parameters dialog.

  4. Click Add to add a new workbook initialization parameter and configure its properties as follows:

  5. Repeat Step 4 as necessary to add other workbook initialization parameters.

  6. Click OK.

    For more information about the workbook Parameters property, see Table A-21.

To configure the worksheet Parameters property:

  1. Open the integrated Excel workbook.

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

  3. Click the browse (...) icon beside the input field for Parameters to invoke the Edit Parameters dialog.

  4. Click Add to add a new worksheet parameter and configure it as in Figure 14-5:

    • (Optional) In the Annotation field, enter a description of the worksheet parameter.

    • In the Parameter field, specify a parameter element that you added to the page definition file associated with the worksheet, as described in Section 14.5.3, "How to Configure the Page Definition File for the Worksheet to Receive Parameters."

    • In the Value field, write an EL expression that references the value of the Parameter property you specified for the workbook initialization parameter (workbook Parameters array). Use the following syntax when writing the EL expression:

      #{workbook.params.parameter}

      where parameter references the value of the Parameter property you specified for the workbook initialization parameter.

    Figure 14-5 Worksheet Parameters

    This image is described in the surrounding text

  5. Repeat Step 4 as necessary to add other workbook initialization parameters.

  6. Click OK.

    For more information about the worksheet Parameters property, see Table A-22.

By default, the workbook parameters are not sent every time the workbook connects to the server to request metadata, the end user logs out, or the session expires. If required, you can configure the workbook to send the initialization parameters by configuring the SendParameters property.

To configure the worksheet SendParameters property:

  1. Open the integrated Excel workbook.

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

  3. In the Edit Worksheet Properties dialog, set the value of SendParameters as shown in the Table 14-2 and Figure 14-6:

    Table 14-2 SendParameters Property

    Set this property to... This value...

    SendParameters

    True to send workbook parameters when the workbook connects to the server to request metadata or data. When set to True, parameters are sent every time when the metadata is requested and the first time when data is requested, during each user session. False is the default value.

    For more information, see Section 15.2, "Restore Server Data Context Between Sessions."

    Figure 14-6 SendParameters Property

    This image is described in the surrounding text

  4. Click OK.

When entering the Test mode, the Workbook Parameter dialog prompts you to enter test parameter values. Figure 14-7 shows the Workbook Parameters dialog that accepts test values for the workbook.

Figure 14-7 Workbook Parameters dialog

This image is described in the surrounding text

You are not required to enter values for any, or all, parameters. If you enter test parameter values, they are not cleared when you exit the test mode and return to design mode. When you run the integrated Excel workbook again, the workbook parameter values are displayed in the Workbook Parameters dialog from the cache.

The provided test values are stored in the workbook in the same way as the ADF Desktop Integration Excel download filter stores the parameter values. When you publish the workbook, the test parameter values are cleared before the workbook is published.

Note:

In the above example, the filterByCitytId method can be used as the worksheet's setup action (SetupActionID). This will cause the method to be called automatically when the worksheet is initialized at runtime (or whenever a new instance of the worksheet's binding container is created). For more information about SetupActionID, see Section 7.24, "Using Explicit Worksheet Setup Action."

The filterByCityId method could also be configured as a part of the action set, such as one for a ribbon command or Startup event, depending on the use case. In the case of a ribbon command, its execution will be triggered by the end user. For more information about ribbon commands and Startup event, see Section 8.3.2, "How to Configure a Worksheet Command for the Runtime Ribbon Tab" and Section 8.2.4, "How to Invoke an Action Set from a Worksheet Event."

Workbook parameter values can be used as arguments for any method exposed by the page definition.

14.5.3 How to Configure the Page Definition File for the Worksheet to Receive Parameters

The page definition file associated with the worksheet in the integrated Excel workbook can be configured as follows:

  • Add one or more parameter elements that initialize the worksheet's binding container. The values for these parameters will be supplied from URL arguments, as specified in Section 14.5.1, "How to Configure the Fusion Web Application's Page to Pass Parameters."

    The following example shows a parameter element in a page definition file that is associated with a worksheet in an integrated Excel workbook:

    <parameters>
    <parameter id="CityIDParam" />
</parameters>

  • Add a method action binding that invokes an application module method (filterByCityId). The application module method takes a single Long argument (CityIdArg) that references the value of CityIdParam. This method is responsible for modifying and executing the view object's query to filter by City ID.

    <bindings>
<methodAction id="filterByCityId" RequiresUpdateModel="true"
              Action="invokeMethod" MethodName="filterByCityId"
              IsViewObjectMethod="false" DataControl="AppModuleDataControl"
              InstanceName="AppModuleDataControl.dataProvider">            
   <NamedData NDName="CityIdArg" NDValue="${bindings.CityIdParam}" 
              NDType="java.lang.Long"/></methodAction>
. . .
</bindings>

For more information about configuring a page definition file, see Section 4.3, "Working with Page Definition Files for an Integrated Excel Workbook."

14.5.4 What Happens at Runtime: How Parameters Are Passed from a Fusion Web Application to the Integrated Excel Workbook

When the end user downloads the integrated Excel workbook from the Fusion web application, the component tag that triggered the download (such as af:link tag) is evaluated, the current CityID is captured and included on the URL. The adfdiExcelDownload filter embeds the names and values of all the parameters from the URL into the downloaded integrated Excel workbook.

The parameters are set into BindingContainer DCParameters before the binding container is refreshed. For more information about how worksheet parameters are mapped to binding containers, see Section 14.5.3, "How to Configure the Page Definition File for the Worksheet to Receive Parameters."

The action set in the worksheet Startup event is also executed during initialization. After initialization, the initialization status for each worksheet is recorded when the integrated Excel workbook is saved to disk.

After the integrated Excel workbook has been saved, closed, and reopened, the first-time initialization is skipped for any worksheets that were previously initialized. If workbook parameters were captured when the integrated Excel workbook was first downloaded, and those parameters are required to set up server context, then the Worksheet.ServerContext.SendParameters property should be set to True. When the SendParameters property is True, workbook parameters are sent on every request for metadata, and also on the first request for data in each user session.

To reset the initialization state for all worksheets in the workbook, invoke the ClearAllData action. For more information about the ClearAllData action, see Table A-20.

14.6 Customizing Workbook Integration Metadata at Runtime

ADF Desktop Integration also supports Oracle Metadata Services (MDS) based runtime customization. For more information about MDS, see the "Customizing Applications with MDS" chapter in Developing Fusion Web Applications with Oracle Application Development Framework.

Workbook integration metadata defines how ADF Desktop Integration components appear and behave in the workbook, and how the workbook is integrated with its Fusion web application. When the workbook is published, its workbook integration metadata XML file is saved at the same location as the design-time copy of the workbook. For more information about publishing a customization-enabled workbook, see Section 14.3, "Publishing Your Integrated Excel Workbook."

The workbook integration metadata files for customization-enabled workbooks need to be deployed to MDS metadata repositories so that they can be managed by MDS. For more information about Metadata Repository, see the "Managing the Metadata Repository" chapter in Administering Oracle Fusion Middleware.

14.6.1 How to Enable Workbook Customization at Runtime

To enable customization of workbook integration metadata, open the Workbook Properties dialog, and set CustomizationEnabled to True.

Before you begin:

It may be helpful to have an understanding of customizing workbook integration metadata. For more information, see Section 14.6, "Customizing Workbook Integration Metadata at Runtime."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 14.1.2, "Additional Functionality for Deploying Your Integrated Excel Workbook."

To enable runtime customization for a workbook:

  1. Open the integrated Excel workbook.

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

  3. Set CustomizationEnabled to True.

  4. Click OK.

  5. Publish the customization-enabled workbook.

14.6.2 What Happens at Runtime: Workbook Integration Metadata is Customized

A customization-enabled workbook obtains its metadata from the server when the workbook is initialized. The integration metadata is managed by MDS on the server end and can be accessed by the application through MDS APIs.

At runtime, the application can provide means for users to customize the workbook integration metadata. When a customization-enabled workbooks is being initialized, it requests the server for workbook integration metadata. MDS applies all the customizations based on current customization context and returns the customized metadata to the workbook for its initialization.

For example, an application can provide a web page where users can customize the columns of a table in a customization-enabled workbook. The user can remove certain columns from the table on the web page and then download the customization-enabled workbook and see the change takes effect in the workbook.

14.6.3 What You May Need to Know About Customizing Workbook Integration Metadata

Customization-enabled workbooks can only be published to a directory under the public_html directory of the associated project. When you deploy your application, make sure that the corresponding workbook integration metadata file can be found by MDS using the metadata path generated when the workbook is published.

Each customization-enabled workbook has its own workbook integration metadata file. When the workbook is published, its workbook integration metadata XML file is saved at the same location as the design-time copy of the workbook. This workbook integration metadata file should be deployed to MDS metadata repositories so that it can be managed by MDS at runtime. In MDS terms, a workbook integration metadata file is a base document and is referenced by MDS using a metadata path. The metadata path is determined when the customization-enabled workbook is published.

For example, if a design-time customization-enabled workbook is published to <PROJECT_HOME>/public_html/myCompany/myPackage/myWorkbook.xlsx and its workbook integration metadata file name is myWorkbook-DT.xlsx-workbook-definition.xml, then the metadata path for this workbook is /myCompany/myPackage/myWorkbook-RT.xlsx-workbook-defintion.xml. At runtime, MDS looks for the workbook integration metadata using this metadata path in the repositories configured with the application. The metadata path must be unique across the application.

By default, if no MDS repository is configured for the workbook integration metadata files, MDS will look up the metadata files on the classpath using the metadata path mentioned. To avoid configuring MDS, you may host the workbook integration metadata files on the classpath of the Fusion web application. The customizations created at runtime can be stored in MDS default-cust-store.