As Published In
Oracle Magazine
November/December 2011

TECHNOLOGY: Business Intelligence


Automating Oracle Business Intelligence Administration


By Mark Rittman Oracle ACE Director


Use the Oracle BI Systems Management API to automate administrative tasks.

If you are a systems administrator responsible for an Oracle Business Intelligence Enterprise Edition 11g deployment, you probably use Oracle Enterprise Manager to perform your management tasks. Using Oracle Enterprise Manager, you can deploy new repositories and catalogs to your Oracle Business Intelligence Enterprise Edition instance and can make configuration changes that update performance parameters, enable query caching, and add extra components to handle system load.

In some cases, it’s more useful to create scripts to handle these tasks. Using scripts, you can apply postinstall changes to a system, deploy changes in bulk across many environments, and automate time-consuming operations to reduce the chance of human error.

With Oracle Business Intelligence Enterprise Edition 11g, two new features now make scripting these tasks possible: the Oracle BI Systems Management API and Oracle WebLogic Server’s WebLogic Scripting Tool. The Oracle BI Systems Management API is a set of Java Management Extensions (JMX) Administration MBeans that provide systems management functionality for a business intelligence domain. WebLogic Scripting Tool is a scripting technology that enables administrators to monitor Oracle WebLogic Server instances and domains.

This article explores how to use these two tools to automate business intelligence tasks.

The Oracle BI Systems Management API

Oracle Enterprise Manager Fusion Middleware Control enables administrators to perform system administration tasks. Behind the scenes, this tool works by accessing a set of JMX Administration MBeans. These MBeans handle a wide range of Oracle Fusion Middleware administration tasks, and the subset specifically associated with business intelligence tasks is called the Oracle BI Systems Management API. Using this API ensures that configuration changes are always applied correctly across every affected component in the cluster.

You can take a closer look at these MBeans and their various attributes and operations by using Oracle Enterprise Manager’s System MBean Browser. 

1. In your Web browser, navigate to http://<host>:7001/em, where “host” is the host name of the server where you have installed Oracle Business Intelligence Enterprise Edition 11g.

2. When prompted, enter the username and password for a valid Oracle WebLogic Server administration user (for example, weblogic/welcome1).

3. After you log in, use the navigation tree on the left-hand side of the page to expand the WebLogic Domain folder and then the bifoundation_domain folder. Right-click the AdminServer entry and select System MBean Browser from the context menu.

4. The System MBean Browser shows a navigation tree displaying all the administration MBeans available from the administration server. Within this list, navigate to Application Defined MBeans -> oracle.biee.admin -> Domain: bifoundation_domain to see a list of all the JMX MBeans available within the Oracle BI Systems Management API.

To view the full API, including descriptions of JMX MBean methods and attributes, consult the Oracle Fusion Middleware System Administrator’s Guide for Oracle Business Intelligence Enterprise Edition, which can be accessed in Javadoc format at ORACLE_HOME/doc/javadoc/bifoundation/jmxapi/index.html.

So what can you do with the API, and how do you use WebLogic Scripting Tool to work with the JMX MBeans? In this article, I’ll use these MBeans to perform a common systems management task: uploading a new business intelligence repository and restarting the server component so that the new repository becomes available for queries.

Using JMX Administration MBeans to Upload a New Repository

The Oracle BI Systems Management API contains three JMX MBeans you need to use to upload a new repository and make it available to users:

  • BIDomainMBean (BIDomain in the System MBean Browser)

  • BIInstanceMBean (BIDomain.BIInstance in the browser)

  • ServerConfigurationMBean (BIDomain.BIInstance.ServerConfiguration in the browser)

The BIDomainMBean is used to lock, activate, or roll back configuration changes to the Oracle business intelligence domain. This MBean is used to implement the Lock and Edit Configuration, Activate Changes, and Release Configuration buttons in Oracle Enterprise Manager.

The BIInstanceMBean contains details of an instance within a business intelligence domain. An instance corresponds to a collection of servers, presentation servers, and other system components within an Oracle Business Intelligence Enterprise Edition 11g system.

The ServerConfigurationMBean actually performs the repository upload. It is one of several MBeans within the Oracle BI Systems Management API that handle a variety of administrative tasks, such as managing the query cache, managing e-mail configurations, adding components to and removing them from the cluster, and configuring security.

To make use of these particular JMX MBeans, you can either invoke their methods manually from the System MBean Browser graphical interface or call them from within a Java application. The latter is what actually happens when you use the Oracle Enterprise Manager console to manage your instance. To implement these same functions from a script, you use WebLogic Scripting Tool.

Scripting the Oracle BI Systems Management API

WebLogic Scripting Tool is a command-line tool for performing administration functions and viewing the configuration state of an Oracle WebLogic Server domain. You can use WebLogic Scripting Tool “online,” typing commands for immediate execution, or “offline,” writing a script for later execution in batch form. You write scripts in a language called Jython, which is an implementation of the Python language in Java. WebLogic Scripting Tool is installed automatically as part of the Oracle Business Intelligence Enterprise Edition 11g initial setup.

The following example shows how to use WebLogic Scripting Tool, along with the JMX Administration MBeans identified earlier, to perform the repository upload task.  

5. Use a text editor on the server hosting Oracle Business Intelligence Enterprise Edition 11g to create the WebLogic Scripting Tool script in Listing 1. 

Code Listing 1: Initial Oracle WLST script 

# Example to demonstrate uploading a new repository using WLST
#
# This script expects the following arguments:
#
# 1. wls.host (localhost)
# 2. wls.port (7001)
# 3. wls.user  (user1)
# 4. wls.password  (password1)
# 5. repository filename and location
# 6. repository password
# ===================================================================
 
import sys
import os
 
# Check that the arguments to this script are as expected.
# argv[0] is script name, [1]-[6] are the user parameters

argLen = len(sys.argv)
if argLen -1 != 6:
    print "ERROR: got ", argLen -1, " args."
    print "USAGE: wlst.cmd RPDUpload.py WLS_HOST WLS_PORT WLS_USER WLS_PASSWORD
 repository_location repository_password"
    print "   eg: wlst.cmd RPDUpload.py localhost 7001 weblogic welcome1
 c:\SampleAppLite.rpd Admin123" 
    exit()
 
WLS_HOST = sys.argv[1]
WLS_PORT = sys.argv[2]
WLS_USER = sys.argv[3]
WLS_PW = sys.argv[4]
rpdlocation = sys.argv[5]
rpdpassword = sys.argv[6]

# Connect to the WLS Admin Server, so that the script then runs “online”
print 'Connecting to '+ WLS_HOST+ ':' + WLS_PORT + ' as user: ' + WLS_USER + ' ...'
 
connect(WLS_USER, WLS_PW, WLS_HOST+ ':' + WLS_PORT);

# Connect to the BIDomainMBean that controls the BI domain
# We will use this MBean to lock and then commit our config changes

print 'Connecting to Domain ...'
domainCustom()

cd ('oracle.biee.admin')

cd ('oracle.biee.admin:type=BIDomain,group=Service')

# define the MBean parameters and datatypes as arrays  
 
objs = jarray.array([],java.lang.Object)
strs = jarray.array([],java.lang.String)

# Invoke the lock operation from the BIDomainMBean
# (equivalent to the Lock and Edit Configuration button in 
# Oracle Enterprise Manager

print 'Locking the domain ...'

invoke('lock',objs,strs)

# Read the name of the first instance from first entry 
# in the BIInstances property within the BIDomainMBean
# (initially returned as an array, first value selected)

biinstances = get('BIInstances')
biinstance = biinstances[0]

# Connect to the corresponding BIInstanceMBean

print ('Connecting to BIInstance MBean')

cd ('..')
cd (biinstance.toString())

# Retrieve the name of the MBean for managing the 
# BI Server configuration

biserver = get('ServerConfiguration')

# Connect to the ServerConfigurationMBean for this BI Server

cd ('..')
cd (biserver.toString())

# Now prepare for the RPD upload
# Prepare arrays for parameters and datatypes
# Load the parameters with the RPD name and password
# Then invoke the uploadRepository within the ServerConfigurationMBean

print ('Uploading repository ...')

argtypes = jarray.array(['java.lang.String','java.lang.String'],java.lang.String)
argvalues = jarray.array([rpdlocation,rpdpassword],java.lang.Object)

invoke('uploadRepository',argvalues,argtypes)

# Now go back to the BIDomainMBean and commit the change
# (equivalent to the Activate Changes button in Oracle Enterprise Manager)

print ('Committing the update ...')

cd('..')
cd('oracle.biee.admin:type=BIDomain,group=Service')
objs = jarray.array([],java.lang.Object)
strs = jarray.array([],java.lang.String)

invoke('commit',objs,strs)

exit()

6. Save the script as RPDUpload.py, and copy it to a temporary directory such as c:\temp on the server.

7. To create a test repository to upload, copy the SampleAppLite.rpd file (which you can usually find at ORACLE_HOME/instances/instance1/bifoundation/coreapplication_obis1/repository/
SampleAppLite.rpd) to the same temporary directory on the server. Rename this file SampleAppLite_test.rpd.

8. Ensure that your business intelligence domain is available and that the Oracle WebLogic Server administration console is running, and then open a command-line terminal on the same server. Navigate to the ORACLE_HOME/Oracle_BI1/common/bin directory, and run the RPDUpload.py WebLogic Scripting Tool script using the command below, substituting your own host name, administration server port, and administration username and password:  

wlst c:\temp\RPDUpload.py 
localhost 7001 weblogic welcome1 c:\temp\SampleAppLite_test.rpd Admin123  

 

9. The script will run and output comments at various stages of the process. 

Next Steps


 READ more Rittman
 

LEARN more about
 Oracle Business Intelligence Enterprise Edition 11g
 Oracle BI Systems Management API

 DOWNLOAD the Oracle WLST script for this article

To check that your new repository uploaded successfully, use your Web browser to navigate to the Oracle Enterprise Manager site at http://<host>:7001/em. Log in using the same Oracle WebLogic Server administration username and password as above, and then use the navigation tree on the left-hand side of the screen to navigate to Business Intelligence -> coreapplication. Using the tabs on the right-hand side of the screen, click Deployment and then Repository, and check that your new repository is listed as the default online repository for your domain.

Restarting Components and Completing the Task

Looking at the repository in Oracle Enterprise Manager, you may notice the warning message “Restart to apply recent changes.” Oracle Enterprise Manager displays this message when you need to restart one or more system components after a configuration change. You can perform the restart by clicking the Restart All button on the Capacity Management -> Availability tab, or you can modify your WebLogic Scripting Tool script by moving the final exit() command to the end of the script and adding the lines shown in Listing 2.

Code Listing 2: Additions to Oracle WLST script 

print ('Now restarting the instance, to pick up the new RPD file')
print 'Connecting to BIInstance MBean ...'
cd ('..')
cd (biinstance.toString())

# The BIInstanceMBean controls the overall status of
# the Oracle instance and, if directed to stop or start,
# will stop/start all components together

print 'Getting instance status ...'

# ServiceStatus property in BIInstanceMBean returns
# the current status of the instance

servicestatus=get('ServiceStatus')
print 'BIInstance MBean; ServiceStatus: ' + servicestatus

# Stop action, if invoked, will stop entire instance

print 'Calling stop ...'
objs = jarray.array([], java.lang.Object)
strs = jarray.array([], java.lang.String)
invoke('stop', objs, strs)
servicestatus=get('ServiceStatus')

print 'BIInstance MBean; ServiceStatus: ' + servicestatus

# Start action will start the instance and pick up
# the configuration change (the new RPD file path)

print 'Calling start ...'
objs = jarray.array([], java.lang.Object)
strs = jarray.array([], java.lang.String)
invoke('start', objs, strs)
servicestatus=get('ServiceStatus')

print 'BIInstance MBean; ServiceStatus: ' + servicestatus

print 'RPD Upload now complete!'

exit() 

You can download the final RPDUpload.py WebLogic Scripting Tool script, including the additional step for restarting the instance.

In Summary

Performing system administration tasks for an enterprisewide distributed Oracle BI system can involve making changes to many components spread over multiple servers. The Oracle BI Systems Management API, part of Oracle Business Intelligence Enterprise Edition 11g, together with WebLogic Scripting Tool, provides a handy command-line environment for managing and propagating changes either interactively or through Jython-based scripts. Use the Oracle BI Systems Management API when you need to deploy repositories, catalogs, or other metadata as part of a systems rollout or when you need to script changes across several environments in a controlled and repeatable manner.
 


Mark Rittman Headshot

Mark Rittman
is an Oracle ACE Director, cofounder of Rittman Mead, and an executive board member of the Oracle Development Tools User Group. He writes for the Rittman Mead blog at rittmanmead.com/blog.

 



Send us your comments