14 Integrating BI Publisher with Enterprise Manager

Overview

In order to integrate BI Publisher with Enterprise Manager 12c, BI Publisher is installed separately, but shares the same Middleware home, as Enterprise Manager. This installation is performed using the standard Business Intelligence Enterprise Edition 11.1.1.6.0 installation that is specific to the platform on which Enterprise Manager is installed. BI Publisher is then integrated into the same WebLogic Server domain as Enterprise Manager using the configureBIP script. Once configured, you will be able to take advantage of the standard features BI Publisher offers, such as:

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

http://www.oracle.com/technetwork/oem/grid-control/downloads/index.html

http://www.oracle.com/technetwork/indexes/documentation/index.html

BI Publisher Installation 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.

cd  <Instance-Home>/user_projects/domains
zip -r GCDomain.zip GCDomain

Checking for SYSMAN_BIPLATFORM schema...
Attempting to create SYSMAN_BIPLATFORM schema...
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: jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=host.com)(PORT=1521)))(CONNECT_DATA=(SID=orcl)))
Connected As: sys
Prefix for (prefixable) Schema Owners : SYSMAN
RCU Logfile: .../middleware/oms/cfgtoollogs/bip/emBIPLATFORM.log
Component schemas created:
Component  Status  Logfile  
Business Intelligence Platform  Success .../middleware/oms/cfgtoollogs/bip/biplatform.log 
Repository Creation Utility - Create : Operation Completed

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

Verifying Integration of BI Publisher with Enterprise Manager

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:

   
   

3. Once BI Publisher has been integrated with Enterprise Manager, you may have to click the refresh icon at the top right of the Enterprise Manager window (highlighted in the previous graphic) in order for the UI to reflect the changes.

4. Enterprise Manager displays a tree list showing all of the Enterprise Manager- supplied BI Publisher reports as shown in the following graphic

   
   

   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.

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

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

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

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:

• Enterprise Manager Authentication Security Model

• BI Publisher security model

• BI Publisher Permissions

• BI Publisher OPSS Application Roles

• Authenticating and limiting access BI Publisher features

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.

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.

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

$MW_HOME/oracle_common/common/bin/wlst.sh [linux]
wlst.cmd [windows]
...
...
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> grantAppRole(appStripe="obi",appRoleName="EMBIPViewer",principalClass="weblogic.security.principal.WLSUserImpl",principalName="JERRY")

Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root. 
 
For more help, use help(domainRuntime)
wls:/GCDomain/serverConfig> exit()

$MW_HOME/oracle_common/common/bin/wlst.sh [linux]
wlst.cmd [windows]
 
...
...
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> revokeAppRole(appStripe="obi",appRoleName="EMBIPViewer",principalClass="weblogic.security.principal.WLSUserImpl",principalName="JERRY")

Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root.

For more help, use help(domainRuntime)
wls:/GCDomain/serverConfig> exit()

Allowing Access to BI Publisher for Enterprise Manager Administrators in an underlying LDAP Authentication security model environment

Enterprise Manager and BI Publisher are separate applications. When using an underlying LDAP-based authentication model, 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.

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

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.

$MW_HOME/oracle_common/common/bin/wlst.sh [linux]
wlst.cmd [windows]
...
...
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> grantAppRole(appStripe="obi",appRoleName="EMBIPViewer",principalClass="weblogic.security.principal.WLSGroupImpl",principalName="EMBIPVIEWER")
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root. 
For more help, use help(domainRuntime)
 
wls:/GCDomain/serverConfig> grantAppRole(appStripe="obi",appRoleName="EMBIPAuthor",principalClass="weblogic.security.principal.WLSGroupImpl",principalName="EMBIPAUTHOR")
Already in Domain Runtime Tree
 
wls:/GCDomain/serverConfig> grantAppRole(appStripe="obi",appRoleName="EMBIPScheduler",principalClass="weblogic.security.principal.WLSGroupImpl",principalName="EMBIPSCHEDULER")
Already in Domain Runtime Tree
 
wls:/GCDomain/serverConfig> grantAppRole(appStripe="obi",appRoleName="EMBIPAdministrator",principalClass="weblogic.security.principal.WLSGroupImpl",principalName="EMBIPADMINISTRATOR")
Already in Domain Runtime Tree
 
wls:/GCDomain/serverConfig> exit()

Configuring BI Publisher with a Custom Trust Store

If you reconfigure your WebLogic Administration 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.

BI Publisher Administration

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

Common administrative tasks:

• Configuring server properties, such as e-mail servers.

• Configuring report delivery channels, such as FTP.

Post-Upgrade Steps to take after upgrading to BI Publisher to 11.1.1.6.0

When performing an upgrade (using the configureBIP -upgrade command) from Enterprise Manager 12c Cloud Control Release 1 (12.1.0.1) that contains an installed BI Publisher 11.1.1.5.0, to Enterprise Manager 12c Cloud Control Release 2 (12.1.0.2), containing BI Publisher 11.1.1.6.0, you need to perform post-upgrade steps. This is required due to the removal of the underscores on all Enterprise Manager-supplied BI Publisher Catalog objects.

1. Any schedules associated with the following eight reports must be stopped [note the underscores]

   EM_Sample_Reports

   Targets_of_Specified_Type

   [Chargeback]

   Charge_Summary_Report

   Charge_Trend_Report

   Usage_Summary_Report

   Usage_Trend_Report

   [Consolidation_Planner]

   Consolidation_Reports

   [Events reports]

   Escalated_Incidents_Report

   Incident_History_Report

   Top_Events_Report

2. The following datamodels [note the underscores] should be deleted from the EM_Datamodels folder:

   Charge_Summary_Report

   Charge_Trend_Report

   Consolidation_Reports

   Escalated_Incidents_Report

   Incident_History_Report

   Target_of_Specified_Type

   Top_Events_Report

   Usage_Summary_Report

   Usage_Trend_Report

3. Delete these folders:

   EM_Sample_Reports

   Consolidation_Planner

4. The following reports must be deleted from their respective folders:

   [Chargeback]

   Charge_summary_report

   Charge_trend_report

   Usage_summary_report

   Usage_trend_report

   [Events]

   Escalated_Incidents_Report

   Incident_History_Report

   Top_Events_Report

Any desired schedules from above that were stopped need to be restarted on the new report names without underscores.

EMBIP* Roles: Granting Access to Folders and Catalog Objects

By default, the shipping security model (as described in Authenticating and limiting access BI Publisher features, 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 BI Publisher 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 the EMBIPAuthor OPSS application role, can develop reports in their own private folders. These reports will not be available to other users.

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.

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.

Troubleshooting

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

emcli login -username=<admin username> -password=<admin password>
emcli sync
emcli setup_bipublisher -proto=http[s] -host=<bip_host> -port=<bip_port>
-uri=xmlpserver

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

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.

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 Allowing Access to BI Publisher for Enterprise Manager Administrators in an underlying LDAP Authentication security model 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.
   

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.

In order to shut down the BI Publisher managed server, do the following:

1. Log in to the AdminServer console as the WebLogic user with the correct password.

2. Click Servers.

3. Click the Control tab underneath the text Summary of Servers.

4. Place a check-mark next to the managed server BIP.

5. Double-check to make sure the check mark is next to the BI Publisher managed server, as opposed to EMGS_OMS1 or EMGC_ADMINSERVER managed servers.

6. Click Shutdown and choose when work completes.

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

1. Navigate to the control page using steps 1-4 above.

2. Place a check mark next to the managed server BIP.

3. Double-check to make sure the check mark is next to the BI Publisher managed server and not the EMGS_OMS1x or EMGC_ADMINSERVER managed servers.

4. Click Start.

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

Configuring BI Publisher behind a Load-Balancer

If BI Publisher is to be run behind a load-balancer, as detailed in the Oracle® Enterprise Manager Cloud Control Administrator's Guide, issue the following commands after all configuration is complete:

emcli login -username=sysman
Password: <sysman_password>
emcli setup_bipublisher -proto=https -host=<load_balancer_host> -port=<load balancer port> -uri=xmlpserver -force -nodeploy