61 Implementing ADF Desktop Integration

This chapter describes how to combine third party desktop applications with Oracle Fusion web applications.

The chapter includes these sections:

• Section 61.1, "Oracle Application Development Framework Desktop Integration Standards and Guidelines"

• Section 61.2, "Skinning Excel ADF Desktop Integration Workbooks"

• Section 61.3, "Configuring the WebLogic Server Frontend"

61.1 Oracle Application Development Framework Desktop Integration Standards and Guidelines

ADF Desktop Integration makes it possible to combine third party desktop productivity applications with Oracle Fusion web applications, so you can use a program like Microsoft Excel as an interface to access Oracle Fusion web application data. Currently, ADF Desktop Integration supports using an Excel workbook to access descriptive and key flexfield data in your application.

ADF Desktop Integration is intended to provide integrated access across a variety of Oracle Fusion products from a variety of third-party interfaces. As a result, it is important that you apply consistent standards for deployment and for look and feel to your implementation of ADF Desktop Integration.

For more general information about integrating Oracle Fusion web applications with desktop applications, see Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.

For information about using ADF Desktop Integration technology with flexfields, see Section 23.14, "Accessing Descriptive Flexfields from an ADF Desktop Integration Excel Workbook" and Section 25.4.5, "How to Access Key Flexfields from an ADF Desktop Integration Excel Workbook".

Important:

The Desktop Integration Developer's Guide does not make explicit reference to technologies documented in this book, and this book does not repeat the content in the Desktop Integration Developer's Guide, so you must read the Desktop Integration Developer's Guide for a full understanding of how to use ADF Desktop Integration technology in general.

Standards for Naming and Organization

ADF Desktop Integration projects have many of the same code artifacts as standard ADF application UI projects. As such, the directory and naming standards for ADF Desktop Integration projects already have a good example to follow.

ADF Desktop Integration artifacts shall follow the same set of directory and naming standards as core ADF UI artifacts. However, you are also encouraged to distinguish your business component names as appropriate. For example, for the General Ledger Journal Entry functionality, the core ADF page has an application module called "JournalEntryAM." For the ADF Desktop Integration Journal Entry, the application module should be given a name similar to "DesktopJournalEntryAM" to prevent duplicate names.

61.1.1 How to Structure the ADF Desktop Integration Directories

The way that you code backing beans, page definitions and JSPX pages for ADF Desktop Integration will be different from the way you code core ADF UIs. For example, JSPX dialogs for ADF Desktop Integration require JavaScript. It is desirable to be able to distinguish between core UI artifacts and UI artifacts used by ADF Desktop Integration workbooks. Therefore, instead of checking in ADF Desktop Integration web picker artifacts into a "ui" package, it is recommended that you instead use a "di" (Desktop Integration) folder. Note that "di" and "ui" are the same length, so path string lengths will not change.

Following is an example of such a directory structure:

|   |   |-- adfmsrc
|   |   |   |-- META-INF
|   |   |   |   |-- <various generated files>
|   |   |   |-- oracle
|   |   |       |-- apps
|   |   |           |-- <LBA Top>
|   |   |               |-- <LBA Core>
|   |   |                   |-- di 
 
 
|   |   |-- public_html
|   |   |   |-- oracle
|   |   |   |   |-- apps
|   |   |           |-- <LBA Top>
|   |   |               |-- <LBA Core>
|   |   |                   |-- di
 

A major benefit to putting ADF Desktop Integration web picker dialog artifacts into a di folder is that automated standards checks can easily distinguish Desktop Integration-related objects and adjust their logic as needed. The directory structure under di will be organized the same way as the directory structure under the ui folder. For example, the bean, controller, page and util folders under di will be found in the same relative locations as the equivalent folders under ui.

The Excel Microsoft Office Open XML Format (XLSX) workbooks (and XLSM files, if required) should be checked into an excel folder within the public_html directory structure:

|   |   |-- public_html
|   |   |   |-- oracle
|   |   |   |   |-- apps
|   |   |           |-- <LBA Top>
|   |   |               |-- <LBA Core>
|   |   |                   |-- di 
|   |   |                       |-- excel
 

Example 61-1 shows some full directory paths for the ADF Desktop Integration artifacts on a Windows system, for a project in a leaf LBA called desktopJournalEntry. The folders contain page definitions, Excel and JSPX files, and beans, respectively:

Example 61-1 Directory Structure in WIndows

D:\FinDashboardPrototype\gl\components\journals\desktopJournalEntry\di\adfmsrc\oracle\apps\financials\generalLedger\journals\desktopJournalEntry\di\pageDefs
 
D:\FinDashboardPrototype\gl\components\journals\desktopJournalEntry\di\public_html\oracle\apps\financials\generalLedger\journals\desktopJournalEntry\di\[excel|page]
 
D:\FinDashboardPrototype\gl\components\journals\desktopJournalEntry\di\src\oracle\apps\financials\generalLedger\journals\desktopJournalEntry\di\bean
 

Example 61-2 shows some directory paths for the ADF Desktop Integration artifacts in source control, for a project in a leaf LBA called desktopJournalEntry. The folders contain page definitions, [excel] and JSPX files, and beans, respectively:

Example 61-2 Directory Structure in Source Control

scs/gl/components/journals/desktopJournalEntry/di/adfmsrc/oracle/apps/financials/generalLedger/journals/desktopJournalEntry/di/pageDefs
 
scs/gl/components/journals/desktopJournalEntry/di/public_html/oracle/apps/financials/generalLedger/journals/desktopJournalEntry/di/[excel|page]
 
scs/gl/components/journals/desktopJournalEntry/di/public_html/oracle/apps/financials/generalLedger/journals/desktopJournalEntry/di/bean
 
scs/gl/components/journals/desktopJournalEntry/di/src/oracle/apps/financials/generalLedger/journals/desktopJournalEntry/di/bean

61.1.2 How to Name Your ADF Desktop Integration Files

Because users can download workbooks to their desktops, providing each workbook with a unique name across applications is advisable. Make an effort to incorporate either the name of your product or the name of the primary Logical Business Object (LBO) involved, to create a meaningful name for your workbook. For example, the expenses workbook could be called ExpensesEntry.xlsx; the General Ledger journal entry workbook could be called JournalEntry.xlsx. However, because there is no current runtime or release requirement for unique names, the ADF Desktop Integration team will not coordinate this.

There is an open question regarding which workbook to source control and release: the design time version or the published version. For now, assume that both versions are source controlled. To that end, the published version should have the final name and the design time version should include the suffix "DT" in its filename. So in the expenses example, two workbooks will be source controlled: ExpensesEntry.xlsx and ExpensesEntryDT.xlsx, where the former is the published version and the latter is the design time version.

61.1.3 How to Implement the Dialog Attributes Declarative Component

The main function of the Dialog Attributes declarative component is to render the ADFDi reserved elements (ADFdi_CloseWindow, ADFdi_AbortUploadOnFailure and ADFdi_DownLoadAfterUpload) in the ADF pages that are used as dialogs in the spreadsheet.

This component replaces the ADFdi_CloseWindow, ADFdi_AbortUploadOnFailure and ADFdi_DownLoadAfterUpload span tags/outputText/JavaScript elements used in JSPX pages to render them as DI dialogs.

Since the component needs to render the value of the span tags (such as ADFdi_CloseWindow) based on the user's use case, it takes as an input the values to be rendered for these tags. To implement this, three properties are exposed on the component, one for each tag (ADFdi_CloseWindow, ADFdi_AbortUploadOnFailure and ADFdi_DownLoadAfterUpload). These properties need to be set based on how the page is used as a dialog in the spreadsheet. An overview of the properties is described in Table 61-1.

Table 61-1 Tag Properties Exposed on the Declarative Component

Component Property	Data Type	Description
closeWindowBinding	String	This property maps to the DI Dom element: ADFdi_CloseWindow The value supplied for this property will be set as the value of the ADFdi_CloseWindow tag. You can bind the property to a backing bean. Example: closeWindowBinding="#{SubmissionOptionsBean.dialogResult}" where dialogResult is a string that is defined in a backing bean and the value is set when the OK or Cancel button is clicked.
downloadAfterUpload	Boolean	This property maps to the DI Dom element: ADFdi_DownLoadAfterUpload This value usually is a constant, such as true or false. It appears in the component property inspector as a list from which you can choose a true/false value. This property needs to be specified only if you are using the dialog as a custom upload dialog. Example: downloadAfterUpload="false"
abortUploadOnFailure	Boolean	This property maps to: ADFdi_AbortUploadOnFailure This value usually is a constant, such as true or false. It appears in the component property inspector as a list from which you can choose a true/false value. This property needs to be specified only if you are using the dialog as a custom upload dialog. Example: abortUploadOnFailure="false"

Note:

If you are using the page as a simple dialog (a basic web picker that only needs ADFdi_CloseWindow), you only need to specify the closeWindowBinding. Do not specify values for the downloadAfterUpload and abortUploadOnFailure properties, which only need to be specified for a custom upload dialog.

61.1.3.1 Adding the Component to Your Page

Before you can add the component to a web page, you need to add its containing JAR file as a library reference.

To add the JAR file as a library reference:

1. Create a file system connection.

   • In the Resource Palette (View > Resource Palette), right-click File System and select New File System Connection.

   • Enter the connection name, such as DI Components, and the directory path as /ade/<view name>/fusionapps/jlib.

   • Test the connection to make sure it is valid. If it is, click OK.

2. Select your user interface project in the application navigator pane.

3. Expand the connection you just created (FileSystem > <connection name>).

4. Right-click the library AdfFinFunPublicDeclarativeComponentsDi.jar and select Add to Project.

5. To make sure the library was added, open Project Properties > Libraries and Classpath > ADF Library. You should see an entry for AdfFinFunPublicDeclarativeComponentsDi.jar.

Once you add the library as a library reference to your project, the component palette will contain the Di Components option that lists all the DI components available for use.

To add the component to the web page:

1. In the component palette (View > Component Palette), select the DialogAttributes component and drag it onto the desired web page.

   The DI component namespace is added to the jsp:root tag at the top of your page:

   <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
   xmlns:h="http://java.sun.com/jsf/html"
   xmlns:f="http://java.sun.com/jsf/core"
   xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
   xmlns:c="http://java.sun.com/jsp/jstl/core" xmlns:di="http://xmlns.oracle.com/apps/financials/common/publicDi/component/diComponents">
   

   The component is rendered as:

   <di:dialogAttributes id="da1" />
   

2. Set the component attributes.

   You can view the available properties on this component by looking at the property inspector. Set the properties as required. The component tag will look like:

   <di:dialogAttributes id="da1"
   abortUploadOnFailure="false"
   downloadAfterUpload="false"
   closeWindowBinding="#{SubmissionOptionsBean.dialogResult}"/>
   

You are now ready to run your project.

61.2 Skinning Excel ADF Desktop Integration Workbooks

Oracle Fusion ADF Desktop Integration workbooks share a common set of style definitions. This enables them to easily apply required changes to the look and feel. The various style definitions that are needed by applications developers are defined in a common Excel styles template file, which is the accurate source for ADF Desktop Integration styles in Oracle Fusion. Figure 61-1 shows an example of the ADF Desktop Integration styles in use; keep in mind that the look and feel is subject to change at any time.

Figure 61-1 Example of ADF Desktop Integration Look and Feel in Excel

61.3 Configuring the WebLogic Server Frontend

When ADF Desktop Integration sends a spreadsheet to the client, it embeds the server public callback address. Then, when the spreadsheet is opened, it is able to authenticate and perform operations on the address.

To set the Frontend URL for the Administration Console:

1. Log in to Oracle WebLogic Server Administration Console.

2. Click Lock & Edit.

3. Expand the Environment node in the Domain Structure window.

4. Click Servers. The Summary of Servers page displays.

5. Select Admin Server in the Names column of the table. The settings page for AdminServer(admin) is displayed.

6. Click the Protocols tab.

7. Click the HTTP tab.

8. Set the Front End Host field to admin.mycompany.com (your LBR address).

9. Save and activate the changes.

To eliminate redirections, you should disable the Administration Console's "Follow changes" feature. To do this, log on to the Administration Console and click Preferences and then Shared Preferences. Clear the Follow Configuration Changes check box and click Save.

To configure HTTP settings for a cluster:

1. If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.

2. In the left pane of the Console, expand Environment and select Clusters.

3. Select the name of the cluster for which you want to configure HTTP.

4. Select HTTP and enter the following HTTP frontend information. These HTTP settings should be set when host information coming from the URL may be incorrect due to a firewall or proxy.

   • Frontend Host

   • Frontend HTTPPort

   • Frontend HTTPSPort

5. Click Save.

6. To activate these changes, in the Change Center of the Administration Console, click Activate Changes. Not all changes take effect immediately; some require a restart.