Oracle® Fusion Middleware Developer's Guide for Oracle Business Intelligence Enterprise Edition 11g Release 1 (11.1.1) E10545-01 |
|
![]() Previous |
![]() Next |
This chapter explains how to add business intelligence objects to ADF applications. Examples of business intelligence objects include analyses, dashboards, and Scorecard components.
This chapter includes the following sections:
"Overview of Embedding Business Intelligence Objects in Applications"
"Business Intelligence Objects That You Can Add to ADF Pages"
"Preparing the ADF Project to Accept Business Intelligence Objects"
"Passing Business Intelligence Content with the Oracle BI EE Contextual Event Action"
"Adding or Modifying a Presentation Services Connection After Deployment"
"Credentials for Connecting to the Oracle BI EE Presentation Catalog"
Embedding business intelligence objects allows you to access the Oracle BI EE Presentation Services 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 a business intelligence object to an ADF page, that page will contain a reference to the business intelligence object and does not contain a copy of the object. When the business intelligence object is modified and saved to the Oracle BI EE Presentation Services 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 2, "Using the Oracle BI EE Logical SQL View Object".
The business intelligence objects that you can include in ADF applications are stored in the Presentation Services 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.)
Use the following use cases to help you better understand why you would embed business intelligence objects in ADF applications. For specific information about creating the business intelligence objects and adding them to an ADF application, see the procedural topics in this chapter as well as Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition and Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
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 report for different regions with conditional formatting and take an action if the sales is trending below a minimum threshold. This report with an action link can be created in the Oracle BI EE application and embedded into the ADF application.
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.
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".
Use this procedure if you are not sure whether you have the required Oracle JDeveloper 11g Release 1 (11.1.1) extensions and Oracle BI EE extensions.
In JDeveloper, click the Help menu and click About. The "About Oracle JDeveloper 11g" dialog displays.
Click the Extensions tab to view a list of the installed extensions. To sort the list, click either the Name or Identifier column heading.
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 WebCenter and Oracle BI EE extensions.
Personalizations for dashboards, dashboard pages, reports, 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
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.
Select Libraries and Classpath.
Click the Add Library button, highlight MDS Runtime and MDS Runtime Dependencies, and click OK.
From the left pane of the Project Properties dialog, select ADF View.
Confirm that the following options are selected:
Enable User Customizations
Across Sessions using MDS
Enable Seeded Customizations
In the Project Properties screen, click OK.
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 Oracle 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. Oracle JDeveloper adds the required BI technologies to the Selected Technologies list.
Click OK.
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. |
To enable secure communication, you must configure Oracle BI EE Presentation Services to communicate over SSL.
For more information about SSL and how to configure it in Oracle Business Intelligence, see Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.
After you configure SSL, you must export the Web application client certificate from the key store and import it into Oracle JDeveloper.
To export and import the client certificate:
Identify the location of the server key store. This path is usually ORACLE_HOME/oraclebi/wlserver_10.3/server/lib/DemoIdentity.jks
Using the server key store location, run the following command:
cd %ORACLE_HOME%/oraclebi/wlserver_10.3/server/lib/
%JAVA_HOME%\bin\keytool -export -alias wlscertgencab -file my.crt -keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase
Import the client certificate into the Oracle JDeveloper IDE. This step prevents SOAP errors from occurring when you create an Oracle Business Intelligence Presentation Services connection.
Copy the certificate into JDeveloper's JRE. The location will be jdev\jdk\jre\lib\security
or oracle\jdk\jre\lib\security
Run the following command to import the certificate. Note that the default password for the Java default keystore file $JAVA_HOME/lib/security/cacerts
is changeit.
keytool -v -import -file my.crt -keystore cacerts
Import the client certificate into JDeveloper's JRE. This step prevents errors from occurring when sending SOAP requests for https://server:port/analytics/saw.dll?privateWSDL
in SSL mode.
Open JDeveloper and locate the -Djavax.net.ssl.trustStore parameter. For example, -Djavax.net.ssl.trustStore= C:\ADE\jdevmain3\oracle\wlserver_10.3\server\lib\DemoTrust.jks.
Note that this parameter contains the client trustStore location and stores the key and certificate that the client uses to verify the server's certificate.
Run the following command to import the certificate to this client trustStore:
%ORACLE_HOME%\oracle\jdk\bin\keytool -import -alias test -file <client_cert_filename> -keystore <keystorefile> -keypass <key_password>
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 Presentation Service 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.
Note: A Presentation Services connection can be added or modified after the ADF application is deployed. For more information, see "Adding or Modifying a Presentation Services Connection After Deployment". |
To create a connection
In JDeveloper, choose where you want the connection to be used.
If you want to create the connection to be available for any JDeveloper application, then navigate to the Resource Palette, click the New button and select New Connections, and then select BI Presentation Services. The Create BI Presentation Services Connection wizard displays.
Note: JDeveloper allows you to drag and drop a saved connection from the Resource Palette to the Application Resources pane. |
If you want to create the connection to be available for the current application, only, then 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.
Enter a unique, descriptive name that identifies the catalog connection. Note that after you finish creating the connection, the name cannot be changed.
Click Next.
Enter the Oracle Business Intelligence Presentation Services location and make selections for the following items:
Protocol– Choose http or https from the drop down list.
BI Presentation Services Host– Type the location of the server where Oracle Business Intelligence is installed, for example, abc12345.mycompany.com.
BI Presentation Services Port– Enter the port number for the host. This number is usually 9704.
BI Presentation Services Virtual Directory– Enter analytics in lower case.
Click Next.
Specify the user name and password for the Presentation Services connection.
Note: When deploying the ADF application, you must change the username and password to Impersonate User credentials. For more information, see Section 1.9, "Credentials for Connecting to the Oracle BI EE Presentation Catalog". |
Click Next
Click Test Connection to verify that the connection information is correct. If your test connection fails, Oracle JDeveloper will provide you with error messages that will help you troubleshoot the problem.
Click Finish to create the connection.
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:
<eventMap xmlns="http://xmlns.oracle.com/adfm/event"> <event name="setParameters"> <producer region="doInputs"> <consumer handler="biExecBinding1"> <parameters> <parameter name="Products.Brand" value="${payLoad.input1}"/> <parameter name='Periods."Year"' value="${payLoad.input2}"/> </parameters> </consumer> </producer> </event> </eventMap>
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.
All business intelligence objects added to the ADF page inherit styles from the current ADF skin.
Before you perform the following tasks, you must have first created an ADF project, prepared it to accept business intelligence content, and created a server connection. For more information about these tasks, see "Preparing the ADF Project to Accept Business Intelligence Objects" and "Creating an Oracle BI EE Presentation Services Connection".
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 Presentation Services Catalog, the Oracle 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.
To either build an expression or bind the content item to a managed bean, click the Ellipsis button. The EL window appears. For more information about building EL expressions or using the EL screen for data binding, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Save the JSPX page.
In the Projects area, which is located in the left pane, locate the file name for the page upon which you are working, right-click, and select Run.
Note that if any type of security was set for the application, you will be prompted for a user name and password.
The Oracle BI EE 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 contextual event action, adds an Invoke a Browser Script action type to the column, and browses for and selects USERSCRIPT.ADFAction. At runtime, the Oracle BI EE 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 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 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 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 contextual event action on the analysis' Employee Name column and include a label of "Promote."
Below is the QDR's definition:
/** * String representation of QDR with use of internal Ids * <pre> * qdr * : '{"_m":' memberGroups (',"_q":' qdrQualifier)? '}' * memberGroups * : '[' memberGroup (',' memberGroup)* ']' * qdrQualifier * : '{' ('"_t":[' scalarMember ']') | ('"_p":[' ('true' | 'false') ']') '}' * memberGroup * : '"_g":{' dimensionMembers (',"_l":' groupQualifier)? '}' * groupQualifier * : '"' ('M' | 'G') '"' * dimensionMembers * : '"' IDENT '":' ('[]' | arrayMembers | hierarchyLevelsMembers) * hierarchyLevelsMembers * : '{' hierarchyLevelMembers (, hierarchyLevelMembers)* '}' * hierarchyLevelMembers * : '"' IDENT '":' ('[]' | arrayMembers) * arrayMembers * : '[' member (',' member)* ']' * member * : scalarMember | arrayMembers | qualifiedMember * scalarMember * : string | number | datetime * datetime * : string * qualifiedMember * : '{"_v":' scalarMember ',"_s":"' ('A' | 'E' | 'T' | 'P') '"}' * IDENT * : ('a' .. 'z' | 'A'..'Z' | '0' .. '9')+ * * _m: member groups * _q: QDR qualifier; _t or _p * _t: target; column identifier * _p: measure target; true or false * _g: member group * _l: member group qualifier; 'M' or 'G' * _v: member value * _s: member special value; 'A', 'E', 'T' or 'P' * * Group Qualifiers: * M - Measure Dimension * G - Selection Group Dimension * For such dimensions, the dimension identifier is irrelevant; we typically make it "_" * For measure dimension, members are measure columns * For selection group dimension, members are group Id Strings * * Qualified Members: Members that are qualified by a special value qualifier such as: * A - All * E - Every * T - Display Total Id * P - Path to catalog object * * Dimension identifier for hierarchical columns is of the form: "dimensionId:hierarchyId" * * <b> * Examples: * </b> * * Region (id "c0") West, East * Year (id "c1") 2000 * {'_m':[{'_g':{'c0':['West','East']}}, {'_g':{'c1':[2000]}}]} * * Region (id "c0") West, East * Year (id "c1") 2000 * Target Region * {'_m':[{'_g':{'c0':['West','East']}}, {'_g':{'c1':[2000]}}], '_q': {'_t':['c0']}} * * Geog dimension (id "d1"), Default hierarchy (id "h1"), State Level (id "l1") CA, WA * {'_m':[{'_g':{'d1:h1':{'l1':['CA','WA']}}}]} * * Geog dimension (id "d1"), Default hierarchy (id "h1"), State Level (id "l1") and City Level (id "l2") CA, WA, SJC * {'_m':[{'_g':{'d1:h1':{'l1':['CA','WA'], 'l2':['SJC']}}}]} * * Region (id "c0") West, East * Measures Sales (id "c3"), Profit (id "c4") * {'_m':[{'_g':{'c0':['West','East']}}, {'_g':{'_':['c3','c4']}, '_l':'M'}]} * * Region (id "c0") West, East * Year (id "c1") 2007, MyFavYears * {'_m':[{'_g':{'c0':['West','East']}}, {'_g':{'c1':[2007,{'_v': 'MyFavYears', '_s':'P'}]}}]} * * Geog dimension (id "d1"), Default hierarchy (id "h1"), State Level (id "l1") CA, WA and City Level (id "l2") MyFavCities * {'_m':[{'_g':{'d1:h1':{'l1':['CA','WA'], 'l2':[{'_v':'MyFavCities', '_s':'P'}]}}}]} * * Region (id "c0") West, East * Measures Sales (id "c3") * Measure Target * {'_m':[{'_g':{'c0':['West','East']}}, {'_g':{'_':['c3']}, '_l':'M'}], ' _q':{'_p':true}} * </pre> * * @param propIdExprMap Map of column expressions key'ed by column Id */
Oracle BI EE provides an ADF MBean that allows you to add a new connection to a deployed BI ADF or WebCenter 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 Oracle Enterprise Manager.
If you did not configure SSL at design time, you can configure it after deployment. For more information, see "How to Configure SSL and Create an Oracle BI EE Presentation Services Connection".
Use the following procedures to add or modify a Presentation Services connection used by a deployed application.
ServletContextListeners register MBeans. If your application is deployed on an Oracle WebLogic Server that was configured with Java Required Files (JRF), the ADF MBean jars and their dependencies are already part of the system classpath and, therefore, you do not need to package other jars with the application.
Use the following step to enable MBeans in your application.
To enable MBeans in Your Application
Open Webapps web.xml.
Specify the ServletContextListeners by adding the following entry to the web.xml.
<listener> <listener-class>oracle.adf.mbean.share.connection. ADFConnectionLifeCycleCallBack </listener-class> </listener> <listener> <listener-class>oracle.adf.mbean.share.config. ADFConfigLifeCycleCallBack </listener-class> </listener> <listener> <listener-class>oracle.bc4j.mbean. BC4JConfigLifeCycleCallBack</listener-class> </listener>
Use the following procedure to configure the connection after the application was deployed.
Open Oracle Enterprise Manager and select your WebLogic domain.
If your application is deployed in the BI ADF domain, select the Application Deployments <your domain>tree node.
If your application is deployed in the WebCenter Spaces domain, select the Web Center tree node, and then select the WebCenter Spaces tree node, and then the webcenter (WLS_Spaces) tree node.
From the list, select System MBean Browser. The System MBean Browser pane displays within the Enterprise Manager page.
In the System MBean Browser pane, navigate to the ADF Connections tree node by following the below path:
Select the Application Defined MBeans tree node.
Select the oracle.adf.share.connections tree node.
Select the Server: <my server name> tree node. For example, Server:DefaultServer or Server:WLS_Spaces.
Select the Application:<your application's name> tree node. For example, Application:Application2 or Application:webcenter.
Select the ADF Connections tree node.
Select the ADF Connections tree node. The corresponding MBean information displays in the Application Defined MBean pane.
In the Application Defined MBean pane, click the Operations tab and then click createConnection/findOrCreateConnection to create a Presentation Services connection.The Operation:createConnection dialog displays.
Specify the required values for the connection. In the connection type Value field, type BISoapConnection. Type a name in the connection name Value field. Click Invoke to create the connection.
In the System MBean Browser pane, click Refresh to refresh the tree so that the new connection displays.
To modify the connection, locate it in the System MBean Browser pane and click it. The connection's information displays in the Application Defined MBean pane.
Click the Attributes tab and enter the BISoap connection information. Click the Apply button to apply your changes.
Click the Operations tab and click save to save the connection.
At design time, you need to specify credentials to connect to the Presentation Services Catalog. These credentials are used to retrieve the list of business intelligence objects (for example, analyses, dashboards, and scorecard components) from the Presentation Services Catalog. For example, if you create the connection using the credentials John.Smith/Password, the catalog will present you with the items available to John.Smith.
After you deploy the application, you can set the location of the Presentation Services Catalog to the catalog used in the deployed environment. At deployment time, you can create and add the Impersonate User credentials to the Oracle BI EE Presentation Services connection. After this is set up and a user accesses an ADF page containing business intelligence objects, Oracle BI EE uses the Impersonate User credentials to connect to the Presentation Services Catalog and impersonate the logged-in user.
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.
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.
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.
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.
Open WebLogic Server for your Oracle BI EE instance.
Locate the Domain Structure pane and select Security Realm. The Realms pane displays.
In the Realms pane, select <myrealm>. The Settings dialog displays.
In the Settings dialog, select the Users and Groups tab.
Confirm that the Users tab is displaying and click New.
Specify BIImpersonateUser for the user name and enter a password.
Click OK.
User the following procedure to use Oracle Enterprise Manager to grant permissions to BIImpersontateUser.
Open Oracle Enterprise Manager for your Oracle BI EE instance.
Locate and select bifoundation_domain. The bifoundation_domain pane displays.
In the bidoundation_domain pane, click the WebLogic Domain list, highlight Security, and select Application Policies. The Search pane displays.
In the Select Application Name to Search field's list, select AdminServer/obi.
Click Create. The Add Permission dialog displays.
In the Permission Class field, select oracle.security.jps.ResourcePermission. In the Resource Name field, select oracle.bi.server.impersonateUser. Click OK.
In the Grantees pane, click Add User. The Add User dialog displays.
In the Available Users list, select BIImpersonateUser and click Move to move it to the Selected Users list. Click OK.
In the bifoundation_domain pane, click OK.