14 Configuring BI Publisher with Enterprise Manager

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.

This chapter covers the following topics:

14.1 Overview

Beginning with Enterprise Manager 12c Release 4 (12.1.0.4), BI Publisher binaries are installed by default, alongside Enterprise Manager. Configuration of BI Publisher is accomplished using the configureBIP script. The configureBIP script performs the following operations:

  • Installs the BI Publisher schema into the Enterprise Manager repository database

  • Integrates BI Publisher into the same WebLogic server domain as Enterprise Manager.

Note:

It is not necessary to perform a software-only install of BI Enterprise Edition (BIEE). Do not install any version of BIEE into the Middleware Home that contains Enterprise Manager.

This process will configure the primary BI Publisher server named "BIP." The primary BI Publisher server is always named BIP.

  • Highly formatted, professional quality, reports, with pagination and headers/footers.

  • PDF, Excel, PowerPoint, Word, and HTML report formats.

  • 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.

Note:

The Information Publisher (IP) reporting framework, though still supported in Enterprise Manager 12c Cloud Control, was deprecated as of Enterprise Manager 12c Release 1 (12.1.0.1). No further report development will occur using the IP framework.

14.1.1 Limitations

The following limitations apply to the use of reports and data sources.

  • Out-of-box reports cannot be edited.

  • If Out-of-box reports are copied, there is no guarantee that the copies will work with future product releases.

14.2 BI Publisher Configuration and Integration with Enterprise Manager 12c

The following procedures assume that you are familiar with both BI Publisher and Enterprise Manager. 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.

For More Information:

For information on configuring BI Publisher storage, see "BI Publisher High Availability" in the Enterprise Manager Administrator's Guide.

For information on developing BI Publisher reports, see the Oracle® Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher.

14.2.1 Installing Enterprise Manager and Required Infrastructure

In order to support the required resources for BI Publisher, the first OMS system (where BI Publisher is initially installed and eventually configured) needs the following additional system requirements above and beyond what is already required by Enterprise Manager:

  • +1.5 GB of RAM minimum. 4 - 5 GB of RAM is recommended for best performance.

  • Beginning with Enterprise Manager 12c Release 4 (12.1.0.4), there are no longer any specific disk space requirements, as the BI Publisher footprint has been dramatically reduced.

For additional resource requirements, see the following support note:

How to Determine the Number of Servers Needed to Run BI Publisher Enterprise in a Production 10g or 11g Environment? (Doc ID 948841.1)

14.2.1.1 Integrating BI Publisher with Enterprise Manager using the configureBIP Script

Integrating BI Publisher with Enterprise Manager requires changing the domain configuration. However, you must first back up Enterprise Manager using standard procedures covered in Enterprise Manager High Availability documentation using the command:

emctl exportconfig oms [-sysman_pwd <sysman password>]
          [-dir <backup dir>]     Specify directory to store backup file
          [-oms_only]             Specify OMS-only backup on Admin Server host
          [-keep_host]            Specify to backup hostname if no slb defined
                                  (Use this option only if recovery will be done
                                   on machine that responds to this hostname)

IMPORTANT:

The configureBIP script must be run as the same operating system user who owns the Oracle Middleware Home.

DO NOT run configureBIP as the Unix Super User (root).

There are two scenarios in which you would run configureBIP:

  • Scenario 1: Fresh Configuration of BI Publisher in Enterprise Manager Release 4 (12.1.0.4)

    The fresh configuration case is used when either of these conditions are met:

    • You are installing Enterprise Manager 12c for the first time. A previous version of Enterprise Manager 12c was not installed previously

    • You are upgrading to Enterprise Manager 12c Release 4 (12.1.0.4) from a previous version of Enterprise Manager 12c and you had not previously installed and integrated the appropriate version of BI Publisher with that prior version of Enterprise Manager 12c.

  • Scenario 2: Upgrade configuration of BI Publisher in Enterprise Manager 12c Release 4 (12.1.0.4) from a previous installation of Enterprise Manager 12c to Enterprise Manager Release 4 (12.1.0.4).

    Use the configureBIP script in upgrade configuration mode if both of the following conditions are true:

    • You have already upgraded a previous release of Enterprise Manager 12c Release 2 (12.1.0.2) or Enterprise Manager 12c Release 3 (12.1.0.3) to Enterprise Manager 12c Release 4 (12.1.0.4)

    • The previous installation of Enterprise Manager 12c had been integrated with the appropriate version of BI Publisher.

The configureBIP script requires the following credentials in order to operate:

  • An Oracle account with SYSDBA privilege; normally the SYS account.

  • The database password for this account.

  • The WebLogic Admin Server password.

IMPORTANT:

Make sure to run the configureBIP from the new 12.1.0.4 Enterprise Manager installation.

Make sure to gather the above credentials before proceeding.

Both the normal mode and upgrade mode of configureBIP are discussed in detail in the following two sections. Be sure to operate the configureBIP script in the appropriate mode for your installation scenario.

14.3 Configure BI Publisher that gets Deployed with Enterprise Manager Release Release 4 (12.1.0.4)

The following steps are performed for a fresh configuration of BI Publisher in Enterprise Manager Release 4 (12.1.0.4). There script executes two major functions:

  • Step 1 - command invocation and credential gathering

  • Step 2 - The creation of the BI Publisher database schema, which is named SYSMAN_BIPLATFORM. This is accomplished using the Oracle Repository Creation Utility (RCU)

  • Step 3 - The WebLogic domain that contains Enterprise Manager is extend to include BI Publisher, and BI Publisher is configured.

Step 1: Command Invocation and Credential Gathering

  1. From the OMS instance's ORACLE_HOME/oms/bin directory (of the current Enterprise Manager 12c Release 4 (12.1.0.4) installation), execute the configureBIP script from the command line. For example:

    cd /oracle/middleware/oms/bin
    configureBIP
    
  2. The script prompts for the necessary credentials.

  3. The script executes the Repository Creation Utility (RCU), since this is normal mode, to create the BI Publisher database schema.

  4. The script prompts for two inputs for the port(s) to use for the BI Publisher Managed Server: One port for non-SSL and one port for SSL. For Enterprise Manager 12c Release 4 (12.1.0.4), it is required that both of these port values be provided.

  5. The script then performs the extend-domain operations.

  6. Enterprise Manager, including BI Publisher, will be set to the same "Lock" mode as it was prior to running configureBIP. This is done via the command "emctl secure {lock | unlock}.

  7. Enterprise Manager is stopped and then started

  8. The Enterprise Manager-supplied BI Publisher Reports are deployed to the newly installed BI Publisher Web application.

  9. The Enterprise Manager WebLogic domain target is refreshed to include the newly added BI Publisher targets.

  10. A backup of Enterprise Manager is performed using emctl exportconfig oms.

    This backup is stored in the instance home directory, under the em/sysman/backup sub-directory. The backup created during the configureBIP script will be the newest file in this directory, after configureBIP is run.

Step 2: Run the Repository Configuration Utility (RCU)

Since you are installing BI Publisher for the first time, the schema will be created using the RCU utility. You should see the something like the following output:

Creating SYSMAN_BIPPLATFORM Schema in EM Repository Database
 
Configuring BI Publisher in Oracle Home located in /oracle/middleware/Oracle_BI1 ... 
Processing command line ....
Repository Creation Utility - Checking Prerequisites
Checking Global Prerequisites
Repository Creation Utility - Checking Prerequisites
Checking Component Prerequisites
Repository Creation Utility - Creating Tablespaces
Validating and Creating Tablespaces
Repository Creation Utility - Create
Repository Create in progress.
Percent Complete: 0
Percent Complete: 10
Percent Complete: 30
Percent Complete: 50
Percent Complete: 50
Percent Complete: 100
Repository Creation Utility: Create - Completion Summary
Database details:
Connect Descriptor                      : (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=em.example.com)(PORT=15044)))(CONNECT_DATA=(SID=emsid)))
Connected As                    : sys
Prefix for (prefixable) Schema Owners : SYSMAN
RCU Logfile                     : /oracle/middleware/oms/cfgtoollogs/bip/emBIPLATFORM.log
Component schemas created:
Component                       Status  Logfile         
Business Intelligence Platform          Success /oracle/middleware/oms/cfgtoollogs/bip/biplatform.log 
 
Repository Creation Utility - Create : Operation Completed

Successfully created SYSMAN_BIPLATFORM schema...

Step 3: WebLogic Domain Configuration

Successful execution of this step displays screen output similar to the following:

Configuring BI Publisher in Oracle Home located in /oracle/work/middleware/Oracle_BI1 ... 
Extending domain with BI Publisher. This operations can take some time. Do not interrupt this command while it is running...
Locking Enterprise Manager ...
OMS Console is locked. Access the console over HTTPS ports.
Restart OMS.
Restarting Enterprise Manager ...
Stopping Enterprise Manager, this can take some time  ...
Starting Enterprise Manager. This operation can take some time. Do not interrupt this command while it is running.
OMS Started Successfully
BI Publisher server named :BIP: running at https://em.example.com:9702/xmlpserver.
Registering BI Publisher with Enterprise Manager and deploying reports...
Performing automatic backup of Enterprise Manager.
Successfully backed up Enterprise Manager.
Successfully setup BI Publisher with Enterprise Manager

14.4 Upgrade Configuration of BI Publisher from an Old BI Publisher Home to a New BI Publisher under the 12.1.0.4 Middleware Home

IMPORTANT:

Stop the BI Publisher server before upgrading. Before beginning the Enterprise Manager upgrade process, you will have stopped the BI Publisher server process using the WLS console. If this has not been performed, then you must use manual system commands to gracefully terminate the BI Publisher server process. For example, on Unix, use the 'kill' command (without the '-9' argument).

The following steps are performed for a upgrade configuration of BI Publisher in Enterprise Manager Release 4 (12.1.0.4). There script executes two major functions:

  • Step 1 - Command invocation and credential gathering

  • Step 2 - The upgrade of the BI Publisher database schema, which is named SYSMAN_BIPLATFORM. This is accomplished using the Oracle Patch Set Assistant (PSA)

  • Step 3 - The WebLogic domain that contains Enterprise Manager is extend to include BI Publisher, and BI Publisher is configured.

From the OMS instance's ORACLE_HOME/oms/bin directory (of the current Enterprise Manager 12c Release 4 (12.1.0.4) installation), execute the configureBIP script with the -upgrade command-line argument. For example:

cd /oracle/middleware/oms/bin
configureBIP -upgrade

Optional: If you do not wish the script to execute step 6 below (the migration of reports and certain configuration data) then an optional command-line argument can be provided. In this situation, you can run configureBIP using the following syntax:

configureBIP -upgrade -nomigrate

  1. The script prompts for the necessary credentials.

  2. The script prompts for the full directory path to the domain of the prior Enterprise Manager 12c installation. This installation already contains the BI Publisher report definitions and certain configuration data.

  3. The script then executes the Patch Set Assistant (PSA) steps to upgrade the BI Publisher database schema, since this is an upgrade from a prior release of the BI Publisher.

  4. The script prompts for the two required inputs for the port(s) to use for the BI Publisher Managed Server. One port for non-SSL and one for SSL.

  5. The script then performs the extend-domain and configuration of the new BI Publisher.The BI Publisher Managed Server is not started in this step.

  6. The script migrates the reports and certain configuration data from the prior installation of BI Publisher, if needed, that was installed onto the prior release of Enterprise Manager 12c.

  7. The script then starts the BI Publisher Managed Server.

  8. Enterprise Manager, including BI Publisher, will be set to the same "Lock" mode as it was prior to running configureBIP. This is done via the command "emctl secure {lock | unlock}.

  9. Enterprise Manager is stopped and then started, including BI Publisher

  10. The Enterprise Manager-supplied BI Publisher Reports are deployed to the newly installed BI Publisher Web application.

  11. The Enterprise Manager WebLogic domain target is refreshed to include the newly added BI Publisher targets.

  12. The Enterprise Manager-supplied BI Publisher Reports are deployed to the newly installed BI Publisher Web application.

  13. The final step performs a backup of Enterprise Manager using the "emctl exportconfig oms" command.

Note:

During an upgrade of BI Publisher 11.1.1.6.0 onto Enterprise Manager 12c Release 3 (12.1.0.4), the existing BI Publisher schema will be upgraded from the prior version to 11.1.1.7.0. This means that when performing an upgrade, all existing BI Publisher schedules will be carried over to the new installation of BI Publisher.

Step 1 - Command invocation and credential gathering

Step 1 generates the following output.

Configuring BI Publisher Version "11.1.1.7.0" to work with Enterprise Manager
Logging started at /oracle/work/middleware/oms/cfgtoollogs/bip/bipca_20140227144257.log.
This command is meant to be run from Oracle Enterprise Manager Cloud Control 12c Release 4. Please confirm? (Y|N):y
Before this command is run, a backup of Enterprise Manager should be performed using the :emctl exportconfig oms: command. Have you made a valid backup of Enterprise Manager (yes/no) [no] ? yes
Enter sysdba user name (sys):
Enter sysdba user password:
Enter Administration Server user password:
Enter the fully qualified path to the domain you are upgrading from: /oracle/EM12cR3/gc_inst/user_projects/domains/GCDomain
Upgrading from a prior release of BI Publisher With a file-system repository Located at: //oracle/EM12cR3/gc_inst/user_projects/domain/GCDomain
Configuring BI Publisher in Oracle Home located in /oracle/work/middleware/Oracle_BI1 ...

Step 2 - The upgrade of the BI Publisher database schema

The schema is named SYSMAN_BIPLATFORM. This operation is performed using the Oracle Patch Set Assistant (PSA).

The patch set assistant runs to upgrade the BI Publisher schema. Output similar to the following will be generated.

EM 12c BIPLATFORMversion 11.1.1.6.0  schema detected. Begin upgrade process to version 11.1.1.7.0
Begin to execute Oracle Fusion Middleware Patch Set Assistant (PSA) ... 
PSA returns with status: 0
Successfully upgraded SYSMAN_BIPLATFORM schema...

Step 3 - The WebLogic domain that contains Enterprise Manager is extend to include BI Publisher, and BI Publisher is configured.

Successful operation of the script generates screen output similar to the following:

Enter an integer between 9701 and 49152 for the BI Publisher HTTP server port. (9701):
Enter an integer between 9713 and 49152 for the BI Publisher HTTPS server port. (9702)):
Extending domain with BI Publisher. This operations can take some time. Do not interrupt this command while it is running...
Migrating BI Publisher Filesystem repository from "/ /oracle/EM12cR3/user_projects/domains/GCDomain/config/bipublisher/repository" to "/oracle/gc_inst/user_projects/domains/GCDomain/config/bipublisher/repository"...
Starting the Upgraded BI Publisher Managed Server...
Locking Enterprise Manager ...
OMS Console is locked. Access the console over HTTPS ports.
Restart OMS.
Restarting Enterprise Manager ...
Stopping Enterprise Manager, this can take some time  ...
Starting Enterprise Manager. This operation can take some time. Do not interrupt this command while it is running.
OMS Started Successfully
BI Publisher server named :BIP: running at https://slc03sag.example.com:9702/xmlpserver.
Registering BI Publisher with Enterprise Manager and deploying reports...
Performing automatic backup of Enterprise Manager.
Successfully backed up Enterprise Manager.
Successfully setup BI Publisher with Enterprise Manager

14.5 Verifying Integration of BI Publisher with Enterprise Manager

Verification can be performed in either fresh configuration mode or upgrade configuration mode.

  1. Log in to Enterprise Manager as a Super Administrator.

  2. From the Enterprise menu, select Reports and then BI Publisher Enterprise Reports.

    Prior to BI Publisher being integrated with Enterprise Manager, the BI Publisher Reports page appears as follows:

    Enterprise Manager pre-integration
  3. After BI Publisher is configured, this same page will display a tree list showing all of the Enterprise Manager-supplied BI Publisher reports, as shown in the following graphic.

    graphic shows the BIP reports listing from the Enterprise Manager console.

    This graphic shows the list of reports after all plug-ins have been installed. The report list will vary in size depending on the number of plug-ins that have been installed.

  4. Click on the provided EM Sample Reports and the select Targets of Specified Type.

  5. Log in to BI Publisher using your Enterprise Manager credentials.

  6. 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 delivery.

14.6 Allowing Access to BI Publisher for Enterprise Manager Administrators

BI Publisher shares the same security model, via WebLogic, that Enterprise Manager is configured to use. The security model is used both for authenticating access to BI Publisher, and also setting up access to different features of BI Publisher. The items to be discussed in the following sections are:

14.6.1 Enterprise Manager Authentication Security Model

Once integrated, BI Publisher Reports conform to the Enterprise Manager authentication security model. Enterprise Manager supports a variety of security models, as defined in the Oracle® Enterprise Manager Security Guide.

To summarize, the security models that Enterprise Manager 12c supports are:

  1. Repository-based Authentication

  2. Enterprise User Security Based (EUS) Authentication

  3. Oracle Access Manager (OAM) SSO

  4. Oracle Single-sign-on (OSSO) -Based Authentication

  5. LDAP Authentication Options: Oracle Internet Directory and Microsoft Active Directory

14.6.2 BI Publisher Security Model

When BI Publisher is integrated with Enterprise Manager, it shares the same security model as Enterprise Manager.

Security Model 1 - Repository-Based authentication, uses the Oracle database for authentication.

Security Model 2, Enterprise User Security Authentication (EUS), uses the Oracle database for authentication. In this security configuration, the Oracle database delegates authentication to an LDAP server. However, this LDAP server is not directly accessed by WebLogic, and therefore BI Publisher does not have direct access to the LDAP server.

The remaining three security models use an underlying LDAP server, which is accessed directly by WebLogic, to authenticate users.

For the purposes of this document, we classify the BI Publisher security model into one of these two categories:

  1. Repository-Based Authentication

  2. Underlying LDAP-based Authentication

    Note:

    When the BI Publisher security model is configured to use Underlying LDAP-based Authentication, no additional BI Publisher-specific configuration is required. For example, you do not need to access the BI Publisher Administration screen and change the security model to LDAP. Because Enterprise Manager and BI Publisher are configured in the same WebLogic domain, they automatically share the same security and authentication mechanisms.

    IMPORTANT:

    If Enterprise Manager was previously configured to use an LDAP or SSO server, these LDAP or SSO configuration steps will have to be repeated. This is required to incorporate required BI Publisher configuration details.

The primary security attributes that apply to BI Publisher Reports are:

Each of these security attributes is detailed in the following sections.

14.6.3 BI Publisher Permissions

Enterprise Manager ships with certain Oracle-provided BI Publisher catalog objects. These catalog objects consist of:

  • Folders

  • Reports (layout definitions and translations)

  • Datamodels (SQL queries against the Enterprise Manager repository)

  • Sub-templates (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 discussed below, achieve the desired security model.

14.6.4 BI Publisher OPSS Application Roles

The domain policy store (OPSS) is used to control Enterprise Manager administrator access to objects in the BI Publisher catalog and conditional access to the BI Publisher "Administration" button.

OPSS is the repository of system and application-specific policies. Details regarding OPSS can be found in the Oracle® Fusion Middleware Application 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 in the same domain, it is necessary to grant specific BI Publisher OPSS application roles to Enterprise Manager administrators in order for them to access and use BI Publisher.

When BI Publisher is installed, four OPSS application roles are created. These four OPSS application roles are combined with the permissions on the BI Publisher catalog objects in the "Enterprise Manager Cloud Control Folder" to achieve the rules shown in the following sections. In addition, when the underlying LDAP authentication security model is used, the LDAP groups can be mapped to these OPSS application roles.

In the Repository-based authentication security model, the domain policy store (OPSS) is used solely to control Enterprise Manager administrator's access to BI Publisher.

14.6.5 Authenticating and limiting access BI Publisher features

Below is a list of the OPSS application roles, and 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 access BI Publisher Reports via any delivery channel that BI Publisher supports, and that has been configured and made accessible the BI Publisher System Administrator. For example, any user can receive BI Publisher Reports via the BI Publisher scheduling and e-Mail delivery mechanism, if configured.

  • EMBIPViewer - Enterprise Manager administrators with this BI Publisher role can receive e-mails plus can view the Enterprise Manager-supplied BI Publisher reports.

  • 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 into their private folder and customize them.

  • EMBIPAdministrator (Super Users) - Enterprise Manager administrators with this BI Publisher role have complete access to BI Publisher.

The following diagram shows the hierarchy of the above roles:

Note:

Access to the BI Publisher "Administration" button is granted via the OPSS application role. This button is used to perform advanced configuration on BI Publisher, such as setting up the e-mail server.
Graphic shows the BIP hierarchy of roles.

Enterprise Manager Super Administrators

When the repository-based authentication security model is used, all Enterprise Manager Super Administrators are automatically granted the EMBIPAdministrator OPSS application role to facilitate setting up BI Publisher.

When an underlying LDAP authentication security model is used, Enterprise Manager Super Administrators are not automatically granted EMBIPAdministrator access to BI Publisher. See Section 16.x for more information on allowing access to BI Publisher for Enterprise Manager Administrators in an underlying LDAP-based Authentication security Model environment.

14.7 Limiting access to BI Publisher features

Granting the previously discussed four OPSS application roles is somewhat different depending on the BI Publisher security model that is in place. To review, the 2 security models that BI Publisher supports are:

  • Repository-Based Authentication

  • Underlying LDAP-based Authentication

14.7.1 Granting BI Publisher OPSS Application Roles to Enterprise Manager Administrators in Repository-Based Authentication Mode Using wlst

An EM CLI command can be used to grant one or more OPSS application roles to Enterprise Manager administrator(s). The following usage example demonstrates using EM CLI to grant VIEW and AUTHOR access to the Enterprise Manager administrators named "JERRY" and "LESLIE".

Note:

Even though Enterprise User Security (EUS) uses an LDAP server for user authentication, this is handled strictly by the database. Therefore, this section also applies when using EUS.

To run the script:

  1. Connect the Enterprise Manager EM CLI to Enterprise Manager

  2. Run emcli grant_bipublisher_roles to grant access to BI Publisher for Enterprise Manager user(s).

Example Session

$ emcli login -username=sysman
Enter password : 
Login successful
$ emcli sync
Synchronized successfully
$ emcli grant_bipublisher_roles  -roles="EMBIPViewer;EMBIPAuthor" -users="JERRY;LELSIE"
EMBIPViewer role successfully granted to JERRY
EMBIPViewer role successfully granted to LESLIE
EMBIPAuthor role successfully granted to JERRY
EMBIPAuthor role successfully granted to LESLIE

Revoking VIEW Access to BI Publisher Reports

In the following example session you revoke VIEW access to BI Publisher reports from user "JERRY".

$ emcli login -username=sysman
Enter password : 
Login successful
$ emcli sync
Synchronized successfully
$ emcli revoke_bipublisher_roles -roles="EMBIPViewer" -users=JERRY
EMBIPViewer role successfully revoked from JERRY

14.7.2 Propagation Time for Changes to OPSS

When changing an Enterprise Manager administrator's BI Publisher access privileges (EMBIPViewer, EMBIPAdministrator, EMBIPScheduler, EMBIPAuthor) the Super Administrator needs to wait 15 or more 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.

14.8 Allowing Access to BI Publisher for Enterprise Manager Administrators in an Underlying LDAP Authentication Security Environment

Enterprise Manager and BI Publisher are separate applications. When using an underlying LDAP-based authentication model (except for Enterprise User Security (EUS)), LDAP groups defined in the external LDAP server can also be used to manage access to BI Publisher. These LDAP groups allow varying levels of access to BI Publisher. Hence, you can add an LDAP user as a member of one or more of these LDAP group and appropriate capabilities of BI Publisher will be exposed. These LDAP groups, which either need to be created or existing ones used, are coordinated with the permissions of the catalog object in the "Enterprise Manager Cloud Control" folder.

Note:

This section does not apply when Enterprise Manager is configured to use Enterprise User Security (EUS). See Section 14.7.1, "Granting BI Publisher OPSS Application Roles to Enterprise Manager Administrators in Repository-Based Authentication Mode Using wlst."

Note:

Because BI Publisher and Enterprise Manager are configured within the same WebLogic domain, it is not necessary to perform any specific LDAP configuration in the BI Publisher application. The following steps are sufficient to configure LDAP.

In an underlying LDAP-based authentication security model, the following steps are required:

  • The administrator of the LDAP server needs to use four external groups of any chosen name. These groups need to be grouped hierarchically. Existing groups can be used, or new ones can be created.

    Important:

    The group names must be all upper-case.

    Group Name Examples:

    • EMBIPADMINISTRATOR

    • EMBIPVIEWER

    • EMBIPSCHEDULER

    • EMBIPAUTHOR

  • The administrator of the LDAP server must then make the additional changes below in order to achieve the necessary hierarchical structure shown in the hierarchy diagram above. For example, using the sample LDAP group names above:

    Make EMBIPADMINISTRATOR a member of EMBIPAUTHOR

    Make EMBIPADMINISTRATOR a member of EMBIPSCHEDULER

    Make EMBIPAUTHOR a member of EMBIPVIEWER

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 LDAP users a members of one or more of the above LDAP groups.

14.8.1 Mapping LDAP Groups to BI Publisher OPSS Application Roles

In order to map the four LDAP groups to the OPSS application roles described above, the LDAP groups need to be mapped using EM CLI.

Note:

If you have just upgraded to BI Publisher 11.1.1.7.0 on Enterprise Manager 12c Release 4 (12.1.0.4) from a prior installation of BI Publisher on Enterprise Manager 12c and the names of your LDAP groups have not changed, this step is not necessary, as the prior OPSS application grants are carried over to the new installation.

Example Session

emcli grant_bipublisher_roles -roles="EMBIPViewer" -external_role="EMBIPVIEWER"
EMBIPViewer successfully granted to EMBIPVIEWER
emcli grant_bipublisher_roles -roles="EMBIPAuthor" -external_role="EMBIPAUTHOR"
EMBIPAuthor successfully granted to EMBIPAUTHOR
emcli grant_bipublisher_roles -roles="EMBIPScheduler" -external_role="EMBIPSCHEDULER"
EMBIPScheduler successfully granted to EMBIPSCHEDULER
emcli grant_bipublisher_roles -roles="EMBIPAdministrator" -external_role="EMBIPADMINISTRATOR"
EMBIPAdministator successfully granted to EMBIPADMINISTRATOR

14.9 Securing BI Publisher with a Secure Socket Layer (SSL) Certificate

The BI Publisher WebLog Server is configured with a default identity keystore ( DemoIdentity.jks) and a default trust keystore ( DemoTrust.jks). In addition, WebLogic Server trusts the CA certificates in the JDK cacerts file. This default keystore configuration is appropriate for testing and development purposes. However, these keystores should not be used in a production environment.

If Enterprise Manager has previously been secured with an SSL certificate, using the emctl secure wls command, this command will need to be re-issued once BI Publisher has been configured. See the Enterprise Manager Administrator's guide for more information on how these commands are used.

14.10 BI Publisher Administration

Please refer to the BI Publisher documentation for instructions on configuring BI Publisher settings.

Common administrative tasks:

14.11 Post-Configuration Steps to take after Configuring BI Publisher

Installing Plug-in-Specific Reports

Some Enterprise Manager-provided BI Publisher reports belong to specific plug-ins. These plug-ins must be installed in order for these reports to be available. A plug-in can be installed before or after BI Publisher is configured to work with Enterprise Manager 12c. Enterprise Manager plug-ins can be installed using different mechanisms. All of these mechanisms support the installation of BI Publisher reports that are part of a plug-in.

Note:

Refer to the Oracle Enterprise Manager Basic Installation Guide for complete installation specifics.

If a Enterprise Manager plug-in was installed prior to BI Publisher being configured, it is necessary to deploy these new BI Publisher reports from Enterprise Manager to BI Publisher. The following command can be used for this purpose:

emcli deploy_bipublisher_reports

For complete usage and examples using this command, execute the following:

emcli help deploy_bipublisher_reports

14.12 EMBIP* Roles: Granting Access to Folders and Catalog Objects

By default, the shipping security model (as described in Section 14.6.5, 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 Section 14.6.3. 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 the EMBIPAuthor OPSS application role, 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 added to this folder hierarchy. The default security model that ships with Enterprise Manager specifically prohibits this.

Note:

Only reports in the "Enterprise Manager Cloud Control" folder will show up in the Enterprise Manager BI Publisher Enterprise Reports menu (From the Enterprise menu, select Reports, and then 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.

14.13 Access to Enterprise Manager Repository

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$ 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.

14.14 Troubleshooting

The following sections provide common strategies that can be used if problems occur with the Enterprise Manager/BI Publisher integration.

14.14.1 Rerunning configureBIP

It is sometimes necessary to rerun configureBIP, either during a fresh BI Publisher configuration, or during an upgrade BI Publisher configuration.Before running to re-run the configureBIP command, stop BI Publisher using this command:

emctl stop oms -bip_only

14.14.2 BI Publisher Log File Locations

The following log files can be used to trace problems to their point of origin.

14.14.2.1 configureBIP Log Files

Location: ORACLE_HOME(oms)/cfgtoollogs/bip/*

  • Creating/upgrading the BI Publisher schema in the database

    • "emBIPLATFORM.log

    • "emBIPLATFORMcreate_<date>.log

    • "biplatform.log

    • "emBIPLATFORMcreate.err

  • Extending the Enterprise Manager domain with BI Publisher

    • "bipca_<date>.log

14.14.2.2 Enterprise Manager BI Publisher Tree and EM CLI Log File Output

emoms.trc

emoms.log

Messages specific to the BI Publisher integration can be found by searching for "BIP" (all caps) in the log files.

14.14.2.3 BI Publisher Runtime

Location: Domain home. For example, gc_inst/user_projects/domains/GCDomain

  • servers/BIP/logs/*

  • servers/BIP/logs/bipublisher.log

14.14.3 Additional Troubleshooting

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

14.14.4 Redeploying All Enterprise Manager-Supplied BI Publisher Reports

If a plug-in is installed subsequent to BI Publisher being installed and configured to work with Enterprise Manager, the BI Publisher reports that are part of the plug-in can be deployed from the Enterprise Manager installation to BI Publisher using the following commands:

emcli login –username=sysman
Password: <pw>
emcli sync
emcli deploy_bipublisher_reports –force

This procedure can also be used to restore reports on BI Publisher if they become damaged.

14.14.5 Enabling BI Publisher Debugging

When troubleshooting BI Publisher, there may be situations that require detailed BI Publisher debugging information to resolve the issues. You can enable BIP debugging using the WebLogic Scripting Tool (WLST). When debugging is enabled, detailed diagnostic and error information will be sent to the standard locations discussed previously, such as bipublisher.log. The following procedure steps you through turning on debugging for the primary BI Publisher server.

Note:

In the following command examples, BIP is the name of the primary BI Publisher server. If there are multiple BI Publisher servers that require debugging, replace the BIP with the individual server names such as BIP2 or BIP3

Once you have finished debugging BI Publisher, be sure to turn off debugging.

14.14.5.1 Turning on BI Publisher Debugging

  1. Before running WLST, set WLST environment properties so that the WebLogic Server trusts the CA certificates in the demonstration trust keystore.

    Linux sh/bash:

    export WLST_PROPERTIES="-Dweblogic.security.TrustKeyStore=DemoTrust"

    Linux csh/tcsh:

    setenv WLST_PROPERTIES "-Dweblogic.security.TrustKeyStore=DemoTrust"

    Windows:

    set WLST_PROPERTIES=-Dweblogic.security.TrustKeyStore=DemoTrust

  2. Connect to WLST.

    Linux:

    $MW_HOME/oracle_common/common/bin/wlst.sh

    Windows:

    %MW_HOME%\oracle_common\common\bin\wlst.cmd

  3. Execute the commands shown in the following WLST session example to enable debugging.

    ...
    ...
    Initializing WebLogic Scripting Tool (WLST) ...
    Welcome to WebLogic Server Administration Scripting Shell
    Type help() for help on available commands
    wls:/offline> connect('weblogic','<pw>','t3s://host:port')
    ...
    ...
    Successfully connected to Admin Server 'EMGC_ADMINSERVER' that belongs to domain 'GCDomain'.
    wls:/GCDomain/serverConfig> setLogLevel(target='BIP',logger='oracle.xdo',level='TRACE:32')
    wls:/GCDomain/serverConfig> getLogLevel(logger='oracle.xdo',target='BIP')
    TRACE:32
    wls:/GCDomain/serverConfig> exit()
    

14.14.5.2 Turning Off BI Publisher Debugging

Once you have finished debugging BI Publisher, you must reset the log-level back to the default setting.

  1. Connect to WLST.

  2. Execute the commands shown in the following WLST session example to disable debugging.

    wls:/offline> connect('weblogic','<pw>','t3s://host:port')
    ...
    ...
    Successfully connected to Admin Server 'EMGC_ADMINSERVER' that belongs to domain 'GCDomain'.
    wls:/GCDomain/serverConfig> setLogLevel(target='BIP',logger='oracle.xdo',level=' 'WARNING:1')
    wls:/GCDomain/serverConfig> getLogLevel(logger='oracle.xdo',target='BIP')
    'WARNING:1'
    

14.15 Managing Enterprise Manager - BI Publisher Connection Credentials

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.

BI Publisher reports displayed through Enterprise Manager

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 12c Cloud Control release 12.1.0.1, you can configure these credentials using the EMCTL command config oms.

Verb Syntax

emctl config oms -store_embipws_creds [-admin_pwd <weblogic_pwd>] [-embipws_user <new_embipws_username>] [-embipws_pwd <new_embipws_pwd>]

The 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:

  1. Create the LDAP user. Example: Create EM_BIP_INTERNAL_USER and assign this LDAP user a password such as XYZ123.

  2. 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 Section 14.8, "Allowing Access to BI Publisher for Enterprise Manager Administrators in an Underlying LDAP Authentication Security Environment".

  3. 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 2
    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 2
    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.
    

14.16 Managing the BI Publisher Server

BI Publisher operates as a separate, managed server in the same WebLogic domain that contains the OMS(s) and the AdminServer. After BI Publisher is configured, the Enterprise Manager emctl command can now be used to also manage BI Publisher.

Usage Examples:

       emctl start oms 
         Starts the Oracle Application Server components required 
         to run the Management Service application.
         Specifically, this command starts the Oracle HTTP Server, 
         Oracle Management Service, BI Publisher server and 
         applications associated with it. 
 
       emctl start oms -bip_only
         Starts just the BI publisher server.
 
       emctl stop oms [-all] [-force] 
         Stops Oracle Management Service.
            -all :  Additionally Stops BI publisher server and 
                    Admin server
            -force : kills the process instead of gracefull shutdown
                    (not recommended)
 
       emctl stop oms -bip_only [-force] 
         Stops BI Publisher server only
            -force : kills the process instead of gracefull shutdown 
                    (not recommended)
 
       emctl status oms
         Displays a message indicating whether Oracle Management 
         Service and BI Publisher are running. 
 
       emctl status oms -bip_only
         Displays a message indicating whether BI Publisher is 
         running. 
 
       emctl status oms -details [-sysman_pwd <pwd>]
         Displays status of Oracle Management Service. It displays 
         detailed information which includes :
           1) Http and Https upload port for Console and Pbs. and 
              respective URL.
           2) Instance Home Location
           3) Oracle Management Service Log directory
           4) Software Load Balancer
           5) Administration Server machine, port and URL
           6) Oracle BI Publisher details 
           -sysman_pwd : Enterprise Manager SYSMAN Password. If not 
                        provided, you will be prompted for this

14.17 Using BI Publisher

For comprehensive information on using BI Publisher, see the BI Publisher documentation library.

http://www.oracle.com/technetwork/middleware/bi-publisher/documentation/index.html

14.18 De-installing BI Publisher that was Not Installed Along with Enterprise Manager 12.1.0.4

IMPORTANT: Do not proceed with this section until the installation of Enterprise Manager 12.1.0.4 has been completed.

If you have followed this chapter to upgrade BI Publisher from a prior release of Enterprise Manager (12.1.0.2 or 12.1.0.3) to 12.1.0.4, and the prior release of Enterprise Manager also contained BI Publisher 11.1.1.6, you can safely remove the prior installation of the BI Publisher Oracle Home, along with the prior installation of the OMS home. As an Oracle-recommended best practice, you should also delete the Oracle home associated with the prior BI Publisher Oracle home since it consumes a significant amount of disk space.

For more information in upgrading Enterprise Manager, when to de-install older Enterprise Manager software, and various de-installation methods, see the Oracle® Enterprise Manager Cloud Control Upgrade Guide.