1.1 Overview of Embedding Business Intelligence Objects in Applications

Embedding business intelligence objects allows you to access the Oracle BI Presentation Catalog and choose Oracle BI EE objects, such as analyses and dashboards, to include in ADF pages. In most cases, the objects that you add to ADF pages are created to fit the theme of an ADF page and application. When you add an object to an ADF page, that page will contain a reference to the object and does not contain a copy of the object. When the object is modified and saved to the Oracle BI Presentation Catalog, any changes will appear in the ADF application when the user runs the form.

After the business intelligence object is added to the ADF page, you can wire it to other regions on the ADF page. You can also set any filter or prompt parameters for the object. You can also set up security and change the Presentation Services connection after the application is deployed.

Note that the Business Intelligence Logical SQL View Object allows you to access the Oracle Business Intelligence Server to create ADF applications that bind native ADF components to Oracle BI EE data. For more information about this method of adding business intelligence data to ADF pages, see Chapter 4, "Using the Oracle BI EE Logical SQL View Object".

1.2 Business Intelligence Objects That You Can Add to ADF Pages

The business intelligence objects that you can include in ADF applications are stored in the Oracle BI Presentation Catalog's folders. You can include the following types of business intelligence objects in ADF applications:

Analyses (Note that you can expand and browse the folders to view an analysis' subcomponents. The following view types appear in the catalog: table, pivot table, chart, funnel chart, gauge, narrative, ticker and title.)

Dashboards (Note that you can browse inside the dashboard folder to find the pages that are associated with the dashboard.)

Dashboard Pages (Note that you cannot browse within the dashboard pages to see components. Such as, any analyses embedded in the dashboard.)

Scorecard components (Note that you cannot include an entire Scorecard; only its components. These components are: strategy maps, strategy trees, KPI watchlists, cause and effect maps, and custom views.)

Supply chain managers want to view the analysis summarizing the status of orders in different sectors and availability of items in the warehouse along with other transactional data.

A marketing manager for an online shopping site wants to see buyers' trend information, such as age group, geographic distribution, and personal interests, in a dashboard to analyze the user data and use it to determine future marketing strategies.

A sales manager wants to see the sales analysis for different regions with conditional formatting and take an action if the sales is trending below a minimum threshold. This analysis with an action link can be created in the Oracle BI EE application and embedded into the ADF application.

1.4 Preparing the ADF Project to Accept Business Intelligence Objects

To properly prepare the ADF project for the addition of business intelligence objects, you must add the required MDS libraries (MDS Runtime and MDS Runtime Dependencies) to the ADF project and add the BI ADF Components technology scope to the ADF project.

1.4.1 How to Prepare the ADF Project

Use the following procedures to prepare the ADF project to accept business intelligence content. Before you can perform the following tasks, you must have created an ADF project to which you will add business intelligence content.

When you have completed the procedures in this topic, you can create an Oracle BI Enterprise Edition Presentation Services connection to access the catalog from which to select business intelligence objects to embed in your application. For more information, see "Creating an Oracle BI EE Presentation Services Connection".

1.4.1.1 Checking for Installed JDeveloper Extensions

Oracle JDeveloper offers the following Oracle BI EE extensions:

Business Intelligence ADF Task Flow

Business Intelligence ADF View Regions

Business Intelligence Composer

Business Intelligence Logical SQL View Objects

Business Intelligence Soap Connection

Use this procedure if you are not sure whether you have the required Oracle JDeveloper 11g extensions and Oracle BI EE extensions.

In JDeveloper, click the Help menu and click About. The "About Oracle JDeveloper 11g" dialog displays where you can confirm the release number.

Click the Extensions tab to view a list of the installed extensions. To sort the list, click either the Name or Identifier column heading.

Note that all Oracle BI EE extensions contain the "bi-" prefix. If no extensions begin with the "bi-" prefix, then you do not have the required extensions.

1.4.1.2 Installing the Required JDeveloper Extensions

Use this procedure to install the required extensions.

From the JDeveloper Help menu, select Check for Updates.

Follow the steps in the wizard to locate, download, and install the Oracle BI EE extensions. If you will create a WebCenter Portal application that integrates with Oracle BI EE, then you need to also install the WebCenter Portal framework.

1.4.1.3 About Oracle BI EE Personalizations in ADF Applications

Personalizations for dashboards, dashboard pages, analyses, and views are saved automatically if the ADF application is configured for personalizations. Personalizations can be stored at the user level or the group level.

Users can personalize the following items when they exist on a dashboard region on an ADF page:

Values for dashboard prompts

Values for presentation variables (These variables are usually set by a prompt.)

Values for column selectors

Drills, sorts, and pivot/swap on a view

Users cannot personalize the following business intelligence content types:

Dashboard pages

Stand-alone Scorecard components

1.4.1.4 Adding the MDS Libraries and Enabling MDS Customizations

If you want to save site and user application personalizations such as prompt values, then you must add the following libraries to the ADF project and confirm that the MDS customizations have been properly enabled. MDS stores application metadata and also stores and retrieves customizations at various levels within the ADF application.

To add the MDS libraries to the ADF project:

In JDeveloper, go to the Project Pane, right click the project to which you want to add the MDS libraries, and select Project Properties.

1.4.1.5 Adding the ADF Technology Scopes

Perform this procedure to add the proper technology scopes to the ADF project.

Technology scopes are ADF project attributes that are used to identify the different technologies used for the project. Selecting the BI ADF Components technology scope adds the ADF Faces, Java, JSF, and JSP and Servlets technology scopes to the ADF project.

To add the ADF technology scopes to the ADF project:

In JDeveloper, go to the Projects Pane and right-mouse click on the project to which you want to add the technology scopes and select Project Properties.

Select Technology Scope.

In the Available Technologies list, select BI ADF Components and click the Add button. JDeveloper adds the required BI technologies to the Selected Technologies list.

Click OK.

1.5 Creating an Oracle BI EE Presentation Services Connection

Before you can add business intelligence objects to an ADF application, you must configure SSL, export and import a certificate, and create a data connection to Oracle BI EE Presentation Services.

Use the following procedures to configure SSL, export and import the certificate, and create a connection to Oracle BI EE Presentation Services. Before you can perform the following tasks, you must have first created an ADF project and prepared it to accept business intelligence content. For more information about preparing the project, see "Preparing the ADF Project to Accept Business Intelligence Objects".

Note:

If you receive a certificate error when using the application, you may need to import the client certificate into your browser.

1.5.1.1 Configuring SSL

To enable secure communication, you must configure Oracle BI EE Presentation Services to communicate over SSL.

1.5.1.3 Creating a connection

You can add connections to one or more installation of Presentation Services. Depending upon where you created and saved the connection, the connection name will appear either within the Resource Palette's IDE Connections panel or the Application Navigator's Application Resources panel.

When you expand the connection's name, JDeveloper shows the Oracle BI Presentation Catalog's folders and the objects stored in the folders. From the folders, you can drag and drop business intelligence objects from the resource palette to the ADF page.

This connection only needs to be built once per catalog; however, after the connection is built, its parameters can be edited at design time within JDeveloper.

JDeveloper allows you to drag and drop a saved connection from the Resource Palette to the Application Resources pane.

Use the following substeps if you want to create the connection to be available for the current application, only:

Navigate to the Application Navigator tab and then to the Application Resources pane., right click on the Connections folder, and select New Connections and then select BI Presentation Services. The Create BI Presentation Services Connection wizard displays.

WSDL Context– Enter the context to which you want to deploy the WSDL application. Modify this field only if the System Administrator has changed the default context from "analytics-ws" to something else. For example, mycompanyname-ws. The SOAP connection will use the context specified in this field.

Static Resources Mode– Specify from where to retrieve static resources.

Select Auto to direct all requests to Oracle BI Presentation Services rather than to the Oracle BI proxy. Selecting Auto results in a significant increase in performance. Note that Auto mode provides the best performance if Oracle WebLogic Server resides behind Oracle HTTP Server or Apache HTTP Server and you are bypassing Oracle WebLogic Server for serving static files.

Select Manual to direct requests to another location. If you select Manual, you must specify a URL in the Static Resources Location field.

Specify the user name and password for the Presentation Services connection.

Note:

If ADF security is enabled for the application, you must change the username and password to Impersonate User credentials before you deploy the application. For more information, see "How to Create and Use Impersonate User".

If ADF security is enabled for your application, set the Perform impersonation when security is enabled field to False to disable the Impersonate User credentials. If you set this field to False, you must also specify the necessary credentials in the User Name and Password fields on this screen. For more information about credentials, see "Credentials for Connecting to the Oracle BI Presentation Catalog".

If ADF security is enabled for your application and you want to use the Impersonate User credentials, leave this field set to True.

If ADF security is not enabled for your application, you do not have to modify this field. This field is only applied to applications where ADF security is enabled.

Click Next

Click Test Connection to verify that the connection information is correct. If your test connection fails, JDeveloper will provide you with error messages that will help you troubleshoot the problem.

Click Finish to create the connection.

1.6 Adding Oracle Business Intelligence Objects to ADF Pages

When you drag and drop a business intelligence object that contains filters or parameters to the JSPX page, JDeveloper inserts the <adfbi:content> element. This tag references a biContent element in the page definition file using the following EL expression:

<adfbi:content id="myBIRegion" value="#{bindings.biContent}"/>

At runtime, this element returns the markup for the selected business intelligence component and defines the parameters that the region can accept as input. There is one parameter for each prompt in the underlying analysis, or one parameter for the underlying filter or prompt for the underlying dashboard. The biContent element contains the default values, and you can edit the values of these parameters and replace them with Expression Language (EL) or literals. This allows you to use JDeveloper's Expression Language to wire the parameters to other components on the page.

The biContent element also accepts the setParameters ADF contextual event. You can map the payload for this event to the parameters exposed by the dashboard region in the pagedef file. For example:

If the dashboard or dashboard page contains analyses that use presentation variables and there are no visible prompts on the dashboard to set these variables, the dashboard designer must add hidden prompts to set the variables. When the dashboard is included on an ADF page, the hidden prompts are available for context passing.

1.6.1 How to Add Business Intelligence Objects to an ADF Page

All business intelligence objects added to the ADF page inherit styles from the current ADF skin.

To add business intelligence objects to an ADF page and specify filter or prompt parameters

In JDeveloper, go to the Resource Palette, select the data connection, and browse for the business intelligence content that you want to add to the ADF page.

Drag and drop the item onto the page.

Note:

If new or revised business intelligence content was saved to the Oracle BI Presentation Catalog, the JDeveloper catalog connection must be refreshed so that all new and revised business intelligence content is available.

If the item includes prompts or filters, the Parameters screen appears, listing the analysis or dashboard prompts and filters. To specify an override parameter value, place your cursor in the Value field and type the parameter value.

The Oracle BI EE ADF Contextual Event action is delivered with Oracle BI EE and uses the Oracle BI EE Action Framework. At design time, the analysis designer determines which column should contain the Oracle BI EE ADF Contextual Event action, and from the New Action Link menu, selects ADF Contextual Event. At runtime, the Oracle BI EE ADF Contextual Event action passes content from the business intelligence object (analysis) to another region on the ADF page or another ADF contextual event on the ADF page.

The Oracle BI EE ADF Contextual Event action takes no parameters and can be conditionally rendered. When the user accesses the ADF page and clicks a data cell containing the Oracle BI EE ADF Contextual Event action or if the cell is tied to a condition and that condition's threshold has been met, the system generates an Oracle BI EE ADF Contextual Event action that has a qualified data reference (QDR) of the cell as its payload.

Suppose that the ADF designer wants to create a business intelligence region on an ADF page that contains functionality that will automatically promote any employee whose three previous employee reviews were rated as "Outstanding." To accomplish this task, the business intelligence content designer would include the Oracle BI EE ADF Contextual Event action on the analysis' Employee Name column and include a label of "Promote."

1.7.2 What Is the Signature of the QDR?

Below is the QDR's signature:

public static QDR fromString(String qdrStr) throws BISvsException

1.8 Adding or Modifying a Presentation Services Connection After Deployment

Oracle BI EE provides an ADF MBean that allows you to add a new connection to a deployed BI ADF or to the WebCenter Portal: Spaces application. You can also modify a deployed application's existing connection. MBeans are deployed with the application and can be accessed post-deployment using Fusion Middleware Control.

1.9 Credentials for Connecting to the Oracle BI Presentation Catalog

At design time, you need to specify credentials to connect to the Oracle BI Presentation Catalog. These credentials are used to retrieve the list of business intelligence objects (for example, analyses, dashboards, and scorecard components) from the Oracle BI Presentation Catalog.

This process ensures that the login to the Presentation Server is the same as the current user of the application and any access checks are performed as the current user, and data is fetched as the current user. If the ADF page contains business intelligence objects to which the user does not have access, the ADF page returns a message stating that the user does not have the proper permissions to access these objects.

1.9.1 How to Create and Use Impersonate User

Use the following procedures to create and use the BIImpersonateUser user to secure an application that uses an Oracle BI EE Presentation Services connection and includes Oracle BI EE objects. ADF security must be enabled for your application before you can apply the impersonate user credentials to the Oracle BI EE Presentation Services connection.

The Impersonate User feature secures applications that contain Oracle BI EE objects when Oracle BI EE and ADF are not sharing an Oracle Internet Directory (OID). Before you begin the process of creating and using Impersonate User, you must confirm that this capability is configured in your environment.

1.9.1.1 Create the BIImpersonateUser

Before you perform this procedure, make sure that either you or the Administrator have created users in the WebLogic Server's Oracle BI EE realm and assigned the BIConsumer role to each user in this realm.

Use the following procedure to use WebLogic Server Console to create the BIImpersonateUser user.