17 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 13c.

This chapter covers the following topics:

• Overview

• BI Publisher Configuration and Integration with Enterprise Manager 13c

• Using Enterprise Manager with BI Publisher

• Paths to Access BI Publisher

• Allowing Access to BI Publisher for Enterprise Manager Administrators

• Limiting access to BI Publisher features

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

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

• BI Publisher Administration

• Post-Configuration Steps to take after Configuring BI Publisher

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

• Access to Enterprise Manager Repository

• Troubleshooting

• Managing Enterprise Manager - BI Publisher Connection Credentials

• Resetting the BISystemUser credentials

• Managing the BI Publisher Server and other Enterprise Manager Components

• Using BI Publisher

• De-installing BI Publisher that was Not Installed Along with Enterprise Manager 13c Release 4

Overview

Beginning with Enterprise Manager 13c Release 1 (13.1.0.0.0), BI Publisher is installed and automatically configured alongside Enterprise Manager. It is not possible to de-install or otherwise de-configure BI Publisher, as it is a base framework component of Enterprise Manager.:

Note:

Under no circumstances should you perform a software-only install of BI Enterprise Edition (BIEE).

Note:

It is no longer necessary to run the configureBIP script in order to configure BI Publisher. BI Publisher will automatically be configured in all Enterprise Manager installation, upgrade, and recovery scenarios.

Note:

Except for a narrow set of special circumstances, it is not supported to run the configureBIP script manually.

BI Publisher Features

BI Publisher feature highlights include:

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

Legacy Information Publisher Reports

The Information Publisher (IP) reporting framework, though still supported in Enterprise Manager 13c 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.

Oracle recommends that all custom Enterprise Manager report development be done using BI Publisher.

Limitations

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

• Out-of-box reports cannot be edited directly.

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

BI Publisher Configuration and Integration with Enterprise Manager 13c

See Installation of Enterprise Manager Cloud Control in the Oracle Enterprise Manager Basic Installation Guideand this guide for detailed information about Enterprise Manager and specific details regarding the automatic configuration of BI Publisher including shared storage and High Availability. Refer to the Enterprise Manager installation and upgrade guide for details regarding BI Publisher and the Shared Location Details page.

In this example, BI Publisher shared storage will automatically be configured in the two volumes /BIP_STORAGE/config and /BIP_STORAGE/cluster. These two volumes can be located on the same system as Enterprise manager. However, if you are currently running Enterprise Manager in a High Availability environment, with multiple OMSs, or plan on doing so in the future, these storage volumes should be located on a remote shared storage device as shown in Figure 17-1. This shared storage device will need to be accessible from all Enterprise Manager systems that are part of the High Availability installation.

Figure 17-1 Shared Storage

All of the BI Publisher report definitions, as well as specific BI Publisher configuration items, are stored in the ‘Configuration Volume'. Therefore, it is very important to institute a reasonable, periodic, backup strategy. The frequency of these backups will depend on how BI Publisher is being utilized.

Additionally, BI Publisher will automatically be ‘enabled' to start at the end of the installation procedure, and every time emctl start oms is run.

Using Enterprise Manager with BI Publisher

Verifying whether your Enterprise Manager installation and BI Publisher are working can be done 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.
3. Since BI Publisher is automatically configured, this page will display 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.

4. Click on the link at the top of the page 'BI Publisher'.
5. Log in to BI Publisher using your Enterprise Manager credentials.

Paths to Access BI Publisher

There are various paths that are used to communicate with BI Publisher. The specific paths that are currently configured can be shown with the emctl status oms -details command.

Note:

Effective use of corporate firewalls may to be used in order to restrict various TCP/IP ports used to access the OMS or BI Publisher.

1. Access to BI Publisher via the list of BI Publisher reports (shown in the prior section). This is the easiest way to access BI Publisher, and requires no special understanding or configuration of the paths below. We call this the 'direct channel'. The 'direct channel' is automatically determined using a heuristic algorithm, based on various configuration settings.

2. Access from the Oracle Management Server (OMS) to BI Publisher. The OMS needs to communicate with BI Publisher in order to perform various operations, such as presenting the list of BI Publisher reports, and deploying new reports. We call this the internal channel. The internal channel is automatically configured when Enterprise Manager is installed or upgraded. The internal channel can also be manually changed at any time using the emcli setup_bipublisher command. See "Managing the BI Publisher Server and other Enterprise Manager Components" for more information about this command.

The two channels are explained in greater detail below:

1. Direct channel: one of the following TCP/IP ports, and communication protocols (HTTP or HTTPS) is used, depending on the method used to access Enterprise Manager, and depending on the Enterprise Manager Authentication Model. The values for all of the BI Publisher ports can be shown using the 'emctl status oms -details' command.

2. If Enterprise Manager has been configured for use with a Server Load Balancer, one or both of the following channels is used. Please consult the Enterprise Manager High Availability guide for further details on the 'emctl secure oms' command and the configuration of a Server Load Balancer for use with Enterprise Manager.

   1. Normally, access will be via Server Load Balancer HTTPS port. This port can be determined with the 'emctl status oms -details' command. This port can be reconfigured using the 'emctl secure oms' command. This command must be run on each OMS system during a rolling down-time procedure.

      Example: emctl secure oms -slb_bip_https_port 5443

   2. If Enterprise Manager has been 'unlocked' using 'emctl secure oms -unlock_console' or 'emctl secure unlock', access via the Server Load Balancer port in HTTP mode is also supported. This channel will be used if Enterprise Manager has been accessed using the Server Load Balancer in insecure mode using HTTP. This only needs to be done on one OMS system, and no down-time is required. For example:

      emctl secure oms -slb_bip_http_port 8080

   3. Access via the secure Oracle HTTPS Server Port (OHS). This will be used if Enterprise Manager has been accessed via the OHS HTTPS port, regardless of whether or not a Server Load Balancer is configured. This port will also be used if Enterprise Manager is configured with a Virtual Hostname.

   4. If Enterprise Manager has been 'unlocked', access via the Insecure Oracle HTTP Server Port (OHS) will be used if Enterprise Manager has been accessed via the OHS HTTP port. This port will also be used if Enterprise Manager is configured with a Virtual Hostname.

   5. If Enterprise Manager is configured to use Single Sign On, and Enterprise Manager is accessed directly on the OMS managed server port, BI Publisher will always be accessed on the secure HTTPS port (thereby by-passing the SSO login screen). This is true regardless of whether Enterprise Manager has been accessed via HTTP or HTTPS mode.

3. Internal Channel: One of the following TCP/IP ports is used. All communications via this channel must remain in HTTPS mode.

   1. Access via the Server Load Balancer in HTTPS mode.

   2. Direct access to the WebLogic managed server on the Secure HTTPS Port.

   3. Access via either OHS port is not supported for the internal channel.

4. Auxiliary Channel: If Enterprise Manager has been 'unlocked', access to the WebLogic managed server can occur on the HTTP port.

Example of using emctl status oms -details to determine the various channels:

emctl status oms -details
Oracle Enterprise Manager Cloud Control 13c Release 4  
Copyright (c) 1996, 2019 Oracle Corporation.  All rights reserved.
Enter Enterprise Manager Root (SYSMAN) Password : 
Console Server Host        : emoms1.example.com
HTTP Console Port          : 7788
HTTPS Console Port         : 7799
HTTP Upload Port           : 4889
HTTPS Upload Port          : 4900
EM Instance Home           : /oracle/gc_inst/em/EMGC_OMS1
OMS Log Directory Location : /oracle/gc_inst/em/EMGC_OMS1/sysman/log
SLB or virtual hostname: slb.example.com
HTTPS SLB Upload Port : 4900
HTTPS SLB Console Port : 443
Agent Upload is unlocked.
OMS Console is unlocked.
Active CA ID: 1
Console URL: https://slb.example.com:443/em
Upload URL: https://slb.example.com:4900/empbs/upload
 
WLS Domain Information
Domain Name            : GCDomain
Admin Server Host      : emoms1.example.com
Admin Server HTTPS Port: 7101
Admin Server is RUNNING
 
Oracle Management Server Information
Managed Server Instance Name: EMGC_OMS1
Oracle Management Server Instance Host: emoms1.example.com
WebTier is Up
Oracle Management Server is Down
JVMD Engine is Down
 
BI Publisher Server Information
BI Publisher Managed Server Name: BIP
BI Publisher Server is Up
 
BI Publisher HTTP Managed Server Port   : 9701
BI Publisher HTTPS Managed Server Port  : 9803
BI Publisher HTTP OHS Port              : 9788
BI Publisher HTTPS OHS Port             : 9851
BI Publisher HTTPS SLB Port             : 5443
BI Publisher HTTP SLB Port              : 8080
BI Publisher is unlocked.
BI Publisher Server named 'BIP' running at URL: https://slb.example.com:5443/xmlpserver
BI Publisher Server Logs: /oracle/gc_inst/user_projects/domains/GCDomain/servers/BIP/logs/
BI Publisher Log        : /oracle/gc_inst/user_projects/domains/GCDomain/servers/BIP/logs/bipublisher/bipublisher.log

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

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 Supported Authentication Schemes in the Enterprise Manager Cloud Control Security Guide.

To summarize, the security models that Enterprise Manager 13c 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
6. Manual WebLogic configuration of other LDAP providers, as supported by Enterprise Manager.

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 four security models, 3 through 6, 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:

   In order for BI Publisher to properly operate with Enterprise Manager, it is very important not to directly change the BI Publisher security model, using the BI Publisher administration screens.. Because Enterprise Manager and BI Publisher are configured in the same WebLogic domain, they automatically share the same security and authentication mechanisms. Changing the BI Publisher security model directly will prevent any logins to BI Publisher.

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

• BI Publisher Permissions

• BI Publisher OPSS Application Roles

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

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.

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

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. However, this privilege does not grant the ability to view the Enterprise Manager-supplied BI Publisher reports. Therefore, Enterprise Manager administrators who need to schedule BI Publisher reports will usually need to be granted the EMBIPViewer privilege.

• 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 email 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 "Allowing Access to BI Publisher for Enterprise Manager Administrators in an Underlying LDAP Authentication Security Environment" for more information.

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 two security models that BI Publisher supports are:

• Repository-Based Authentication

• Underlying LDAP-based Authentication

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 17-1 Example Session

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

Example 17-2 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

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.

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

Prerequisite Step

Before the BI Publisher access model can be used in an underlying LDAP authentication security environment, the default Oracle Virtual Directory (OVD) configuration must be altered to support LDAP lookups for Enterprise Manager Administrators. This change is required to insure that LDAP lookups for both the Oracle Management Server (OMS) and BI Publisher, function properly.

In the configuration file adapters.os_xml there are two specific properties that need to be configured.

• The priorities of the following 3 providers must have the same value, usually 50:

  • DefaultAuthenticator

  • emgc_USER

  • emgc_GROUP

  • Any LDAP providers that have been configured for use with Enterprise Manager. An Example is OID_Provider.

• The following property must be set to the value false

  • useCaseInsensitiveSearch

This file is located in the WebLogic domain for Enterprise Manager 13c. The exact file location is:

gc_inst/user_projects/domains/GCDomain/config/fmwconfig/ovd/default/adapters.os_xml

This file edit needs to be made on the system housing the primary Oracle Management Server (OMS) and WebLogic Administration Server.

After this edit is made, a rolling bounce of the complete Enterprise Manager stack must be performed on all Enterprise Manager systems. To do so, perform the following steps:

1. Edit adapters.os_xml file on the primary OMS system.

2. On all Enterprise Manager Systems, in order from the first OMS system to the last execute the following:

   1. emctl stop oms –all –force

   2. emctl start oms

The following MOS note provides further details, and a small shell script to assist with making this change:

• Enterprise Manager 13c Requirements for using BI Publisher alongside the OMS in an underlying LDAP Authentication Security Environment. (Doc ID 2260665.1)

Before the BI Publisher access model can be used in an underlying LDAP authentication security environment, the following command must be run:

Details of using BI Publisher with LDAP

Note:

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

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 to be granted to multiple Enterprise Manager Administrators. Hence, you can add an LDAP user as a member of one or more of these LDAP groups 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.

If your corporate standards prevent the creation of new LDAP groups for use with Enterprise Manager, the steps in "Granting BI Publisher OPSS Application Roles to Enterprise Manager Administrators in Repository-Based Authentication Mode Using wlst" can continue to be used for Enterprise Manager users that are managed by the LDAP server.

Note:

Because BI Publisher and Enterprise Manager are configured within the same WebLogic domain, it is important not 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 recommended:

• The administrator of the LDAP server needs to use four external groups of any chosen names. These groups need to be grouped hierarchically. Existing groups can be used, or new ones can be created. For purposes of this document, we use the below examples:

  Note:

  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.

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.

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

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

The BI Publisher WebLogic 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 is secured with an SSL certificate, using the emctl secure wls and/or the emctl secure oms and/or emctl secure console commands, BI Publisher will be likewise configured. See the Enterprise Manager Security guide for more information on how these commands are used.

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

• Configuring report delivery channels, such as FTP.

Post-Configuration Steps to take after Configuring BI Publisher

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 an Enterprise Manager 13c installation or upgrade.

Note:

See Installation of Enterprise Manager Cloud Control in the Oracle Enterprise Manager Basic Installation Guide for complete installation specifics.

If an Enterprise Manager plug-in is installed after the initial installation or upgrade of Enterprise Manager 13c, it will be 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

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.

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.

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.

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

Note:

Except for a narrow set of special circumstances, it is not supported to run the configureBIP script manually.

BI Publisher Log File Locations

The following log files can be used to trace problems to their point of origin. Use the following command to locate the specific directories for each:.

emctl status oms -details

Automatic Configuration of BI Publisher

The following locations log files pertain to BI Publisher automatic configuration that takes place during Enterprise Manager installation.

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

Enterprise Manager BI Publisher Tree and EM CLI Log File Output

Messages specific to BI Publisher integration can be found by searching for "BIP" (all capital letters) in the emoms.trc and emoms.log files.

Additional Troubleshooting

If BI Publisher is able to run successfully, but BI Publisher registration with Enterprise Manager fails (errors are generated when the configureBIP script is executed), 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

Redeploying All Enterprise Manager-Supplied BI Publisher Reports

If the Enterprise Manager-supplied BI Publisher reports become damaged, the following procedure can be used to restore them:.

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

The BI Publisher reports that are part of a plug-in that is installed subsequent to BI Publisher being installed and configured to work with Enterprise Manager can also be deployed with this command.

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 log levels indicate the type of debugging information that will appear in the log files:

Table 17-1 Log Levels for Debugging

Message Type	Level	Description
ERROR	1	A serious problem that requires immediate attention from the administrator and is not caused by a bug in the product.
WARNING	1	A potential problem that should be reviewed by the administrator.
NOTIFICATION	1	A major lifecycle event such as the activation or deactivation of a primary sub-component or feature. Level 1 is the default level for NOTIFICATION.
NOTIFICATION	16	A finer level of granularity for reporting normal events.
TRACE	1	Trace or debug information for events that are meaningful to administrators, such as public API entry or exit points.
TRACE	16	Detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem.
TRACE	32	Very detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem.

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.

Turning on BI Publisher Debugging

1. If Enterprise Manager is still configured with the Demo SSL certificates, it is first necessary to set a system environment variable before using wlst. Therefore, 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()
   Please enter your username :weblogic
   weblogic
   Please enter your password :
   Please enter your server URL [t3://localhost:7001] :t3s://em.example.com:7101
   t3s://em.example.com:7101
   ...
   ...
   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()
   

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.

   Initializing WebLogic Scripting Tool (WLST) ...
   Welcome to WebLogic Server Administration Scripting Shell
   Type help() for help on available commands
   wls:/offline> connect()
   Please enter your username :weblogic
   weblogic
   Please enter your password :
   Please enter your server URL [t3://localhost:7001] :t3s://em.example.com:7101
   t3s://em.example.com:7101
   setLogLevel(target='BIP',logger='oracle.xdo',level=' 'WARNING:1')
   wls:/GCDomain/serverConfig> getLogLevel(logger='oracle.xdo',target='BIP')
   'WARNING:1'

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.

When Enterprise Manager Cloud Control is first installed, a dedicated WebLogic user is automatically created with the requisite credentials solely for the purpose of installation/configuration. Beginning with Enterprise Manager 13c Cloud Control release 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. For example, if the user specified is part of the embedded LDAP server that is included with WebLogic, use the WebLogic console to set the password. If the user specified is part of a corporate LDAP server, set the password there.

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 Environment.
3. Execute the EMCTL config oms command:

   emctl config oms -store_embipws_creds
   Oracle Enterprise Manager Cloud Control 13c Release 4
   Copyright (c) 1996, 2019 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 13c Release 4
   Copyright (c) 1996, 2019 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

Resetting the BISystemUser credentials

In order for BI Publisher to function properly, a special user is created as part of Enterprise Manager installation. This user is the 'BISystemUser'. The credentials for this user are created using a secure random password generator when BI Publisher is first configured, as part of Enterprise Manager installation or upgrade.

If it is necessary, due to corporate policies or procedures, to reset this password, the following command can be run:

emctl config oms -change_bisystemuser_pwd [-admin_pwd <pwd> {[-user_pwd <pwd>] | [-auto_generate]}

The new password can either be automatically regenerated, or a specific password can be provided at the command-line.

Here are some examples:

emctl config oms -change_bisystemuser_pwd
Oracle Enterprise Manager Cloud Control 13c Release 4  
Copyright (c) 1996, 2019 Oracle Corporation.  All rights reserved.
Enter Admin User's Password : 
Enter BISystemUser's Password : 
Successfully updated credentials for BISystem account.

emctl config oms -change_bisystemuser_pwd -auto_generate
Oracle Enterprise Manager Cloud Control 13c Release 4  
Copyright (c) 1996, 2019 Oracle Corporation.  All rights reserved.
Enter Admin User's Password : 
Successfully updated credentials for BISystem account.

emctl config oms -change_bisystemuser_pwd -admin_pwd <entermypassword>
Oracle Enterprise Manager Cloud Control 13c Release 4  
Copyright (c) 1996, 2019 Oracle Corporation.  All rights reserved.
Enter BISystemUser's Password : 
Successfully updated credentials for BISystem account.

emctl config oms -change_bisystemuser_pwd -admin_pwd <entermypassword> -user_pwd <entermypassword>
Oracle Enterprise Manager Cloud Control 13c Release 4  
Copyright (c) 1996, 2019 Oracle Corporation.  All rights reserved.
Successfully updated credentials for BISystem account.

emctl config oms -change_bisystemuser_pwd -admin_pwd <entermypassword> -auto_generate
Oracle Enterprise Manager Cloud Control 13c Release 4  
Copyright (c) 1996, 2019 Oracle Corporation.  All rights reserved.
Successfully updated credentials for BISystem account.

Managing the BI Publisher Server and other Enterprise Manager Components

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 independent of the OMS. All of the commands operate properly, regardless of the current state of the component being operated upon. For example, if the OMS is already running, executing emctl start oms will report this, and not attempt to start it again. As another example, if BI Publisher is already stopped, 'emctl stop oms -all' will report this, and not attempt to stop it again.

Command Operations

emctl start oms

This command starts all of the required components in order to run Oracle Enterprise Manager. Specifically, this command starts the following components, in the following order:

• WebLogic Node Manager

• WebLogic Administration Server

• Oracle Management Service, including JVMD Manager

• Oracle WebTier

• BI Publisher server

emctl start oms -bip_only

Starts the following Enterprise Manager components:

• WebLogic Node Manager

• WebLogic Administration Server

• Oracle WebTier

• BI Publisher server

For all of the combinations of the emctl stop oms command below, the optional argument '-force' causes the command to use the Node Manager to stop the Enterprise Manager component(s).

emctl stop oms [-force]

Stops the following Enterprise Manager components: Oracle Management Service, including JVMD Manager.

Note: This command does not operate on any other components of Enterprise Manager.

emctl stop oms -bip_only [-force]

Stops the following Enterprise Manager component: BI Publisher Server

Note: This command does not operate on any other components of Enterprise Manager.

emctl stop oms -all

This command Stops all components of Enterprise Manager. Specifically, this command stops the following components, in the following order:

• Oracle WebTier

• Oracle Management Service, including JVMD Manager

• BI Publisher server

• WebLogic Administration Server

• WebLogic Node Manager

emctl status oms

Displays a message indicating the status of all Enterprise Manager components

emctl status oms -bip_only

Displays a message indicating the status of BI Publisher.

emctl status oms -details [-sysman_pwd <pwd>]

This command displays status of all Enterprise Manager components. It displays detailed information which includes:

• HTTP and HTTPS upload port for Console and Pbs,.and their respective URLs.

• Instance Home Location

• Oracle Management Service Log directory

• Software Load Balancer or Virtual Server details

• Administration Server machine, port and URL

• Oracle BI Publisher details, including all configured TCP/IP ports, and the location of the BI Publisher log files.

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

De-installing BI Publisher that was Not Installed Along with Enterprise Manager 13c Release 4

IMPORTANT: Do not proceed with this section until the installation of Enterprise Manager 13c Release 4 has been completed.

If the prior release of Enterprise Manager also contained BI Publisher, 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 may consume 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 Enterprise Manager Cloud Control Upgrade Guide.