Applies to:

Purpose

Troubleshooting Hyperion Business Rules issues with an emphasis on using Business Rules with Hyperion Planning.

Last Review Date

Instructions for the Reader

Troubleshooting Details

Overview:

This guide presents potential solutions to common issues surrounding the use of Hyperion Business Rules with Hyperion Planning. These issues include:

• No Rules visible in Planning web or Smart View
• Incorrect Rules visible in Planning web
• Errors when trying to create or edit a rule in the EAS/AAS console

The potential solutions are presented in order of increasing complexity.

I. Recycling services

• Stop EAS/AAS service, Planning service, and RMIRegistry service.please not that restarting the services purges the EAS.HBRPLUGIN table so it is necessary to log into Planning after a restart to make the locations visible in the EAS console.
• Start all three services again.
• Log into your application(s) in Planning web. You need to log into every application once, in order to make the locations available in EAS/AAS. It does not matter what user you log in with. Once you have logged in, you can log out again. *
• Log into the EAS/AAS console as an EAS/AAS administrator (e.g. “admin”) and refresh users from the "Administration" node under "Business Rules" (right-click on it > Refresh User List).
• Log out of EAS/AAS and then log back in, this time as a Planning administrator (for all Planning applications, if you want all locations to be available).
• Test the creation of a new rule with a Planning location, and the validation of an existing rule.

II. HBRServer.properties file is present and correct

• Check that the HBRServer.properties file is present in the same folder as the Planning properties file (HspJSHome.properties in 4.1.1.1 to 9.2.x, or PlanningSystemDB.properties in 9.3.x) under your Planning web application deployment.
• Check that HBRServer.properties is not an empty file. It should be around 4K in size.
• Check HBRServer.properties contains up-to-date connection information for the EAS/AAS relational database. The HBR.catalog= parameter should contain the name of the database.
• If the HBRServer.properties file is missing, empty, or out of date, take a copy from the \Hyperion\AdminServices\ directory on the EAS/AAS server and place it in the same directory as the Planning properties file under the Planning web application deployment.
• If you make any changes to the HBRServer.properties file, or copy it over from the EAS/AAS server, you will need to restart the Planning service at a minimum. To be sure changes have taken effect, restart all three services as in (I) above, and log into Planning web as in (I) above.

III. Testing connectivity

The RMIRegistry service acts as a connector between EAS/AAS and Planning. It enables EAS/AAS to authenticate against Planning locations. It is not needed to enable Rules to be displayed and to run in Planning web. Problems with this service typically result in Planning locations being inaccessible from within EAS/AAS.

• Is the RMI service running properly? Open a command prompt window and type
  
  telnet 11333
  
  You should get a connection (a black screen) rather than an error. Try this from the Planning server (where RMI is installed) and from the EAS/AAS server.
  
  Note that there have been a few cases where RMI seems to be available to telnet to but was not working correctly and needed reinstalling.
  
• Check the Hyperion\common\RMI\1.0.0\ directory:
  • HyperionRMIRegistryStdOut.log and HyperionRMIRegistryStdErr.log files are useful to confirm that the service started successfully and to troubleshoot errors.
  • Check that the HspJS.jar file (in the Hyperion\HyperionPlanning\Utils directory in 9.2.x and 9.3.0.1, in Hyperion\Planning\lib in 9.3.1) is referenced in the HyperionRMI_Classpath.properties file and is actually present.
    
• Uninstall and then reinstall the RMI service using the utilities in Hyperion\common\RMI\1.0.0\
  • Stop the RMIRegistry service
  • Run Hyperion\common\RMI\1.0.0\UninstallHyperionNTServiceRMI.cmd
  • Run Hyperion\common\RMI\1.0.0\InstallHyperionNTServiceRMI.cmd
    
• The RMI service can be configured to use a different port. Check the Hyperion\common\RMI\1.0.0\HyperionRMI_Port.properties file to see what port RMI is listening on (11333 by default). You may have to change the port if you have a port conflict with another product such as Hyperion Application Link (HAL).
  
• Check that the EAS/AAS relational database is accessible (try to ping the server) and check the username and password settings, as these could have changed. You can run the Hyperion Configuration Utility and configure EAS/AAS again to re-enter the database connection details. This will update the HBRServer.properties file with the repository connection details. Copy this updated version of HBRServer.properties over from Hyperion\AdminServices\ on the EAS/AAS server to the Planning properties file directory on the Planning server and restart the Planning service. Note that the configuration utility encrypts the password for you so it will not be visible in plain text in the properties file.
  
• Start the Planning web application service in the foreground (stop it as a service then launch it from the Start Menu), then login to an application in Planning web as the application owner. If Planning can successfully use the information in HBRServer.properties to locate and connect to the EAS/AAS relational database you should see the following message in the console: "HBR connection created successfully".
  
• If the rules do not run from the Planning web but do run from EAS/AAS, and Planning and EAS/AAS are on different severs, then the EDS URL may need to be modified. Try replacing the EDS URL in the HBRServer.properties used by Planning (then copy to the same folder as the Planning properties file) to:
  
  tcpip://PlanningServer:5001
  
  Note that you should use the Planning server hostname, not the EAS one. Then restart the Planning service for the change to take effect.

IV. Users and rights

You do not need to provision users for the "Business Rules" roles in Shared Services in order to use Business Rules with Planning. This role is used for provisioning users to use Business Rules with Essbase. If you provision a Planning user as a "Planner" they will have the ability to launch rules they are given access to. If you provision a Planning user as "Administrator" they will be able to edit, create, and manage rules associated with this Planning location.

• Essbase users refresh: log into EAS/AAS as a user with administrator rights to the Essbase server and refresh users from the "Security" node under the Analytic Server (right-click on it > Refresh from Shared Services). This will refresh any new users from Shared Services.
  
• HBR users refresh: log into EAS/AAS as a user with business rules rights (see below for the necessary user rights) and refresh users from "Administration" node under Business Rules (right-click on it > Refresh User List). This refreshes the list of Business rules users and their rights (what rules they are allowed to use).
  
• Rather than using the 'admin' user, try creating a new native user (called “hbradmin” for example), and provision with the following rights in shared services:
  • Administrator for all Planning applications in Shared Services
  • 'Administrator' for business rules
  • Server access for analytic server

Then log into planning web with hbradmin (for each application if there are several). Then log into AAS as admin and perform. a security refresh from Shared Services (right-click on Security) and an HBR users refresh (see above). Now log out and back into AAS as hbradmin.

V. DEBUGGING

• The HBR server can be set to debug mode. Change the line:
  
  log4j.logger.com.hyperion.hbr=WARN
  
  to DEBUG in the HBRServer.properties file. HBRServer.log will then contain more information.
  
• If you suspect that Shared Services is causing a problem you can isolate EAS/AAS from Shared Services and make it use native security. Use the configuration utility to unregister EAS/AAS from Shared Services. You can then edit OlapAdmin.properties and set HUB_enabled=false
  
• If you get an error message similar to
   An HBR object was not retrieved from the EAS xml transfer object
  when trying to validate or launch a Rule in AAS, locate the essbase.properties file in \Hyperion\AdminServices\server\bin and find the system.dataDir= parameter (it may be commented out). Set it to system.dataDir=./data and restart the EAS/AAS service. This directory will be created under Windows\system32.
  
• The HBRPluginData table in the EAS/AAS relational database is the place where EAS/AAS stores the list of Planning locations that are available. An entry is added to it when a user first logs into Planning web after a services restart. If all applications have been logged into, there should be one record for each Planning application. The contents of this table can safely be deleted during troubleshooting, as the entries will be recreated when the Planning application is next used.
  
• When used in conjunction with an Oracle relational database, HBR usernames can cause problems because of case sensitivity. Check the HBR_UGOBJLINK table in the AAS relational to see what users are provisioned for HBR. Compare the usernames here with those users listed in the Access Permissions tab for a business rule.