|Oracle® Enterprise Manager Cloud Control Advanced Installation and Configuration Guide
12c Release 1 (18.104.22.168)
Oracle Business Intelligence (BI) Publisher is Oracle's primary reporting tool for authoring, managing, and delivering all your highly formatted documents. BI Publisher ships standard with Enterprise Manager Cloud Control 12c.
IMPORTANT:Only BI EE 22.214.171.124.0, which contains BI Publisher 126.96.36.199.0, is supported for use with Enterprise Manager 12c Cloud Control 188.8.131.52.
This chapter covers the following topics:
Though BI Publisher is still deployed as a separate installation, Enterprise Manager can be configured to integrate a BI Publisher installation within an Enterprise Manager domain: BI Publisher is installed into the same WebLogic Server domain as Enterprise Manager. Once configured, you will be able to take advantage of the standard features of BI Publisher such as:
Highly formatted, professional quality, reports, with pagination and headers/footers.
PDF, Excel, Powerpoint, Word, and HTML output of reports.
Develop your own custom reports against the Enterprise Manager repository. (read-only repository access)
Integration with Enterprise Manager Security.
Grant varying levels of BI Publisher functionality to different Enterprise Manager administrators.
Use BI Publisher's scheduling capabilities and delivery mechanisms such as e-mail and FTP.
Format (report) can be edited separately from the data definition (data model).
Standardized Enterprise Manager subtemplate for headers.
Full NLS support for BI Publisher Report output.
Note:The Information Publisher (IP) reporting framework is still supported for Enterprise Manager 12c, however, new report development using this framework has been deprecated for Enterprise Manager 12c release 184.108.40.206.
The following are limitations apply to the use of reports and data sources.
There is no guarantee that the data sources will remain consistent from release to release.
Out-Of-The-Box reports cannot be edited.
If Out-Of-The-Box reports are copied, there is no guarantee that the copies will work with future product releases.
Only Oracle Business Intelligence (BI) Publisher version 220.127.116.11.0 can be used with Enterprise Manager Cloud Control 18.104.22.168. Oracle BI Publisher version 22.214.171.124.0 or later are not compatible with Enterprise Manager Cloud Control 126.96.36.199. You can download Oracle Business Intelligence Publisher version 188.8.131.52.0 directly from the Enterprise Manager Cloud Control download Web site.
See the link titled Oracle Business Intelligence Publisher 184.108.40.206.0.
The following procedures assume that you are familiar with both BI Publisher and Enterprise Manager installations. Refer to the Oracle Enterprise Manager Basic Installation Guide and the Oracle Enterprise Manager Advanced Installation and Configuration Guide for detailed information about Enterprise Manager.
Both Enterprise Manager and BI Publisher must be installed with a centralized inventory file. This means that
/etc/oraInst.loc points to the same directory for both installs. Although it is possible to install both products with a special inventory specific to each product, this configuration is not a supported and will not allow complete integration between Enterprise Manager 12c and BI Publisher 11g.
In order to support the required resources for BI Publisher, the first OMS system (where BI Publisher is initially installed) needs the following additional system requirements above and beyond what is already required by Enterprise Manager:
+1.5 GB of RAM
+7 GB of disk space
Any additional OMSes that are added to the domain, after BI Publisher has been installed on the first OMS, will also require an additional 7 GB of disk space.
Run the Enterprise Manager 12c installer. Some Enterprise Manager-provided BI Publisher reports are part of the Chargeback and Trending plug-ins. These plug-ins must be installed in order for these reports to be available. They can be installed using any supported Enterprise Manager installation method.
Note:Refer to the Oracle Enterprise Manager Basic Installation Guide for complete installation specifics.
Important: Integration requires Oracle Business Intelligence Enterprise Edition 11g (version 220.127.116.11.)
Do a software-only install of BI EE using the below steps:
Run the BI EE Publisher Installer: (Disk1/runInstaller).
(Optional) Choose E-Mail address for updates and click Next.
VERY IMPORTANT: Choose the Software-only Install.
Click Next. Prerequisite checks will run.
After passing prerequisite checks run, click Next.
Choose the Middleware home of your Enterprise Manager installation. This is the Middleware home that you created previously.
BI Oracle Home name must be left as the default Oracle_BI1. Click Next.
(Optional) Enter MOS credentials to be notified of security updates. Click Next.
When the software-only install of BI EE completes successfully, proceed to Integrating BI Publisher with Enterprise Manager Using the configureBIP Script.
Integrating BI Publisher with Enterprise Manager will require changing the domain configuration. It is highly recommended to back up the domain in case of unforeseen errors during configuration. File permissions for the domain files must be maintained when creating a backup. For example, from the
<Instance_Home>/user_projects/domains directory, run:
zip -r GCDomain.zip GCDomain
From the OMS instance's
ORACLE_HOME/bin directory, execute the configureBIP script from the command line. The script takes four inputs and then performs the Repository Creation Utility (RCU) step and then takes two more inputs, performs the extend-domain operations and finally deploys the Enterprise Manager- supplied BI Publisher Reports to the newly installed BI Publisher Web application.
Enter a database user with SYSDBA privileges (typically 'sys'), then enter the password. (Enterprise Manager repository database)
Enter the adminserver and then the nodemanager password. These accounts are part of Enterprise Manager WebLogic Domain.
Script Operation (RCU Steps)
Script Operation describes what the configureBIP script is doing.
RCU runs to create the BI Publisher schema. Note there will be some output printed on the screen.
You will know that RCU was successful, if you see the following:
... ... Repository Creation Utility - Create : Operation Completed
Extend Domain Steps
You will then be asked to enter BI Publisher HTTP and HTTPS ports (either one or both). The script will identify free ports and ask if you want to take them as a default. Once entered, Extend Domain will then run
The Enterprise Manager-supplied BI Publisher Reports will be deployed to the newly installed BI Publisher Web application.
Once processing is complete, you will see something like the following screen output:
Extending domain with BI Publisher. This may take a few minutes... BI Publisher server running at http://host.us.oracle.com:9701/xmlpserver. BI Publisher server running at https://host.us.oracle.com:9702/xmlpserver. Registering BI Publisher with Enterprise Manager and deploying reports... Successfully setup BI Publisher with Enterprise Manager
Log in to Enterprise Manager.
From the Enterprise menu, choose Reports and then BI Publisher Enterprise Reports.
Click the refresh icon at the top right of the Enterprise Manager window.
Enterprise Manager displays a tree list showing all of the Enterprise Manager- supplied BI Publisher reports as shown in the following graphic.
Click on the provided Enterprise Manager Sample Report: Targets_of_Specified_Type
Log in to BI Publisher using your Enterprise Manager credentials.
You will see the sample report rendered on the screen. You can then use the full capabilities of BI Publisher such as PDF report generation and e-mail.
Once integrated, BI Publisher reports conform to the Enterprise Manager security model. The primary security attributes that apply to BI Publisher Reports are:
Roles (or groups in the LDAP case)
Enterprise Manager ships with certain Oracle-provided BI Publisher catalog objects. These catalog objects consist of:
Reports (layout definitions and translations)
Datamodels (SQL queries against the Enterprise Manager repository)
Subtemplates (standard Enterprise Manager header shown above all pages of all report output)
These catalog objects are created when BI Publisher is installed and integrated with Enterprise Manager. They are placed in the "Enterprise Manager Cloud Control" folder. These catalog objects are created with certain permissions that, combined with the roles/groups below, achieve the desired security model.
When BI Publisher is installed, four roles are created (non-LDAP), or in the LDAP case, four groups need to be created. These roles/groups are combined with the permissions on the catalog objects in the aforementioned folder to achieve the rules shown in the following sections.
Below is a description of the effective security model placed on BI Publisher catalog objects that ship with Enterprise Manager.
None - Enterprise Manager administrators without any BI Publisher role can receive BI Publisher Reports via delivery channels such as e-mail or FTP.
EMBIPScheduler - Enterprise Manager administrators with this BI Publisher role can receive e-mails and can schedule the Enterprise Manager-supplied BI Publisher reports if they also have the EMBIPViewer role.
EMBIPAuthor - Enterprise Manager administrators with this BI Publisher role can receive e-mails, view the Enterprise Manager-supplied BI Publisher reports, and can create new reports in their private folder. They can also copy the Enterprise Manager-supplied BI Publisher reports and customize them.
The following diagram shows the hierarchy of the above roles:
Enterprise Manager Super Administrators
In a non-LDAP environment, all Enterprise Manager Super Administrators are automatically granted the EMBIPAdministrator role to facilitate setting up BI Publisher.
In an LDAP environment, Enterprise Manager Super Administrators are not automatically granted EMBIPAdministrator access to BI Publisher. See Granting the EMBIP* roles to Enterprise Manager/BI Publisher Administrators for more information on allowing access to BI Publisher for Enterprise Manager Administrators in a LDAP environment.
In the non-LDAP case, the domain policy store (OPSS) is used to control Enterprise Manager administrator access to objects in the BI Publisher catalog.
OPSS is the repository of system and application-specific policies. Details regarding OPSS can be found in the Oracle® Fusion Middleware Security Guide. In a given domain, there is one store that stores all policies (and credentials) that all applications deployed in the domain may use. As both Enterprise Manager and BI Publisher are separate applications, it is necessary to grant BI Publisher specific roles to Enterprise Manager administrators
In a non-LDAP environment, the command-line tool wlst.sh (on wlst.batMicrosoft Windows) is used to manipulate the OPSS.
wlst.sh (on wlst.bat Microsoft Windows) can be used to grant access to the BI Publisher UI to Enterprise Manager administrators.
The following wlst.sh usage example demonstrates of using wlst.sh to grant view access to the Enterprise Manager administrator named "JERRY" (italicized items are entered at the command-line). It is important to use uppercase letters for Enterprise Manager Administrator names.
$MW_HOME/oracle_common/common/bin/wlst.sh wls:/EMGC_DOMAIN/serverConfig> connect('weblogic','<pw>','t3s://host:port') wls:/EMGC_DOMAIN/serverConfig> grantAppRole(appStripe="obi",appRoleName="EMBIPViewer",principalClass="weblogic.security.principal.WLSUserImpl",principalName="JERRY")
To revoke access to View BI Publisher reports from the user JERRY (case is important), enter the following:
When changing an Enterprise Manager administrator's BI Publisher access privileges (EMBIPViewer, EMBIPAdministrator, EMBIPScheduler, EMBIPAuthor) the Super Administrator needs to wait 15 minutes for the changes to propagate through OPSS and become effective. The change will then be effective the next time the administrator logs into BI Publisher.
As both Enterprise Manager and BI Publisher are separate applications, it is necessary to grant BI Publisher specific roles to Enterprise Manager administrators, which in this case are groups defined in the external LDAP. These different BI Publisher groups allow varying access to the BI Publisher UI. So, you can add an external LDAP user as a member of one or more of these external LDAP group above, and BI Publisher will expose specific parts of the BI Publisher UI to that user when they log in to BI Publisher. These groups, which need to be created as described in the following section, are coordinated with the permissions of the catalog object in the "Enterprise Manager Cloud Control" folder.
In an LDAP environment, similar concepts are employed to grant access to BI Publisher for different Enterprise Manager administrators. However, in an LDAP environment, Enterprise Manager administrators credentials are stored in the LDAP system.
In order to achieve the required security model described in BI Publisher Security Model, the following steps must be performed:
The administrator of the LDAP server needs to create the following four external groups:
Make EMBIPAdministrators member of EMBIPAuthors
Make EMBIPAdministrators member of EMBIPSchedulers
Make EMBIPAuthors member of EMBIPViewers
Note:In LDAP, the terminology and concepts can seem backwards and confusing. For example, you want the EMBIPAuthors group to have as a member the EMBIPAdministrators group.
Then, in order to grant access to BI Publisher and its catalog objects, the administrator of the LDAP server needs to make respective Enterprise Manager/LDAP users a member of one or more of the above LDAP groups.
If you reconfigure your AdminServer to use a custom trust store, then you must also configure BI Publisher accordingly. This also requires the trust store for the OMS to contain the certificate for the BI Publisher-managed server.
In order to use a trusted certificate from a signing authority, create a Java Key Store (JKS) containing the user certificate of BI Publisher server.
Note:If you use an e-mail server with SSL, you will need to add the e-mail server's certificate to your trust store as well.
Please refer to the BI Publisher documentation for instructions on configuring BI Publisher settings.
Common administrative tasks:
By default, the shipping security model (as described in BI Publisher Security Model, applies to BI Publisher catalog objects that are inside the "Enterprise Manager Cloud Control" folder. This is due to the fact that the catalog objects that exist in this folder are set up with a default set of permissions. See Permissions. BI Publisher catalog objects that are outside of this folder will not automatically contain these same permissions. For example, BI Publisher ships with numerous reports in a shared folder called "Samples". If it is desired to grant access to this folder to Enterprise Manager/BI Publisher users, other than EMBIPAdministrator, it is necessary for a BI Publisher super administrator (EMBIPAdministrator) to change the permissions of this folder. They do so by selecting the folder "Samples" and choosing "Permissions" in the bottom left task bar. They then need to add the four privileges (EMBIPAdministrator, EMBIPViewer, EMBIPAuthor, EMBIPScheduler) and grant appropriate access to that privilege such as View report, run report online, to EMBIPViewer. The administrator can model the appropriate privileges to grant based on any of the shipping Enterprise Manager reports (for example, Targets_of_Specified_Type).
Individual users, who have EMBIPAuthor, can develop reports in their own private folders. These reports will not be available to other users.
Note:The shared folder "Enterprise Manager Cloud Control" contains Enterprise Manager- provided BI Publisher Reports and is reserved for such. No custom-developed reports may be put in this folder hierarchy, and the default security model that ships with Enterprise Manager specifically prohibits this.
Note:Only reports in the "Enterprise Manager Cloud Control" will show up in the Enterprise Manager BI Publisher Enterprise Reports menu (Enterprise -> Reports -> BI Publisher Enterprise Reports).
If a BI Publisher administrator (EMBIPAdministrator) wishes to create a new shared folder outside of the "Enterprise Manager Cloud Control" folder, they can do so. These reports would not show up in the Enterprise Manager BI Publisher reports menu but would be available to other Enterprise Manager administrators as long as appropriate permissions are granted as previously described.
All BI Publisher reports are granted read-only access to the Enterprise Manager Repository. This access is via the BI Publisher data source named EMREPOS. This access is via the Enterprise Manager user MGMT_VIEW, which is a special internal Enterprise Manager user who has read-only access to the Enterprise Manager Published MGMT$ and GC$ database views. In addition, when reports are run, they are further restricted to the target-level security of the user running the report. For example, if user JOE has target-level access to "hostabc" and "database3", when user JOE runs a BI Publisher report (any report) he can only view target-level data associated with these two targets.
Before attempting to re-run configureBIP, be sure to kill any existing BI Publisher processes.
If BI Publisher is able to run successfully, but BI Publisher registration with Enterprise Manager fails, you can retry the registration by running:
emcli login -username=<admin username> -password=<admin password> emcli sync emcli setup_bipublisher -proto=http[s] -host=<bip_host> -port=<bip_port> -uri=xmlpserver
If the domain becomes corrupted, and you created a backup of your domain, you can restore your domain using the backup file.
Stop the OMS and AdminServer using
emctl stop oms -all
<Instance_Home>/user_projects/domains, move the <domain name> folder, and unzip the backed up <domain name> folder into its place.
Restart the OMS and AdminServer using
emctl start oms.
Accessing BI Publisher from Enterprise Manager requires a direct connection between the two products in order to retrieve, display, and manage report definitions. Example: From the Enterprise menu, choose Reports and then BI Publisher Enterprise Reports. A tree view displaying BI Publisher reports within the Enterprise Manager Cloud Control shared folder appears as shown in the following graphic.
The first time you run the
configureBIP script to configure BI Publisher to integrate with Enterprise Manager, a dedicated WebLogic user is automatically created with the requisite credentials solely for the purpose of installation/configuration. Beginning with Enterprise Manager release 18.104.22.168.1, you can configure these credentials using the EMCTL command
emctl config oms -store_embipws_creds [-admin_pwd <weblogic_pwd>] [-embipws_user <new_embipws_username>] [-embipws_pwd <new_embipws_pwd>]
config oms command allows you to change the password, and optionally the username, used by Enterprise Manager to access the installed BI Publisher Web Server. Running the
config oms command requires the WebLogic Admin user's password.
Note 1: The
config oms command only changes the user credentials required for the Enterprise Manager - BI Publisher connection. The Enterprise Manager - BI Publisher connection credentials should match the credentials used elsewhere by the user. Example: Enterprise Manager users (database authentication), LDAP users, and WebLogic Server users. Use the corresponding application/console to create or manage the user within the installed credential store.
Note 2: This command is operational only if BI Publisher has been installed.
Note 3: It is not necessary to restart any managed server, such as EMGC_OMSnnnn or BIPnnnn.
Any valid credential that WebLogic supports is acceptable as long as that user also has the EMBIPAdministrators privilege (either in OPSS or LDAP, as appropriate).
Example: You have configured Enterprise Manager to use single sign-on (SSO) (backed by an LDAP credential store). The following steps illustrate the credential update process:
Create the LDAP user. Example: Create EM_BIP_INTERNAL_USER and assign this LDAP user a password such as XYZ123.
Make EM_BIP_INTERNAL_USER a member of the EMBIPAdministrators LDAP group. For more information about LDAP groups and Enterprise Manager-BI Publisher integration, see Allowing Access to BI Publisher for Enterprise Manager Administrators in a LDAP environment.
Execute the EMCTL
config oms command:
emctl config oms -store_embipws_creds -embipws_user EM_BIP_INTERNAL_USER Oracle Enterprise Manager Cloud Control 12c Release 22.214.171.124.0 Copyright (c) 1996, 2012 Oracle Corporation. All rights reserved. Enter Admin User's Password: <pw> Enter new password that Enterprise Manager will use to connect to BI Publisher : XYZ123 Successfully updated credentials used by Enterprise Manager to connect to BI Publisher.
If you later change the EM_BIP_INTERNAL_USER password in the LDAP server, you can change the LDAP user's password by executing the
config oms command with the
-store_embipws_creds option. In the following example, the password is changed to ABC123.
emctl config oms -store_embipws_creds Oracle Enterprise Manager Cloud Control 12c Release 126.96.36.199.0 Copyright (c) 1996, 2012 Oracle Corporation. All rights reserved. Enter Admin User's Password: <pw> Enter new password that Enterprise Manager will use to connect to BI Publisher : ABC123 Successfully updated credentials used by Enterprise Manager to connect to BI Publisher.
BI Publisher operates as a separate, managed server in the same WebLogic domain that contains the OMS(s) and the AdminServer.
In order to shut down the BI Publisher managed server, do the following:
Log in to the AdminServer console as the WebLogic user with the correct password.
Click the Control tab underneath the text Summary of Servers.
Place a check-mark next to the managed server BIP.
Double-check to make sure the check-mark is next to the BI Publisher managed server, as opposed to EMGS_OMSx or EMGC_ADMINSERVER managed servers.
Click Shutdown and choose when work completes.
Wait until BI Publisher has shut down. You can monitor the status of this operation by clicking on the refresh icon (the two arrows in a circle) above the text Customize this Table.
To start the BI Publisher managed server, do the following:
Navigate to the control page using steps 1-4 above.
Place a check-mark next to the managed server BIP.
Double-check to make sure the check-mark is next to the BI Publisher managed server and not the EMGS_OMSx or EMGC_ADMINSERVER managed servers.
Wait until BI Publisher has started. You can monitor the status of this operation by clicking on the refresh icon (the two arrows in a circle) above the text Customize this Table.