Oracle Essbase connector

With the Oracle® Essbase® connector, you can use commands in a chain to interact with Oracle Essbase. For example, with this connector, you can:

• Execute calculation, MaxL, and report scripts in Oracle Essbase
• List and manage Essbase databases, applications, and variables
• Upload, download, and delete files in Oracle Essbase

Note: This connector supports Oracle Essbase 11.1.2.2.x, 11.1.2.3, 11.1.2.4, and 11.2.

Prerequisites

To enable the connection, the connector uses the Oracle Essbase Java® API, secured via basic username and password authentication. To set up the connection, you'll need:

• A designated GroundRunner set up for the connector
• A designated integration user set up in Oracle Essbase for the connector
• The integration user's authentication credentials
• The base URL of the Essbase instance to connect to
• The name of the Essbase cluster to connect to
• The path to these Essbase client Java archive (JAR) files:
  • ess_es_server.jar
  • ess_japi.jar
  • ess_maxl.jar
• Whether the Essbase instance has Embedded Mode enabled

Note: The integration user requires permissions applicable to the commands the connector performs.

Locate the Essbase client JAR files

To enable the connection, the connector requires client JAR files located in the Oracle Essbase installation; by default:

• For Microsoft® Windows®, C:\Oracle\Middleware\EPMSystem11R1\common\EssbaseJavaAPI\11.1.2.0\lib
• For Linux, /User/username/Oracle/Middleware/EPMSystem11R1/common/EssbaseJavaAPI/11.1.2.0/lib

If the GroundRunner and Oracle Essbase are installed on different servers, copy the JAR files to a folder on the GroundRunner's server, and note the path to the folder for the connector's Java API Path property.

Set up the Oracle Essbase connector

Note: To make the connector available for use in your organization's chains, an org security administrator first enables it from Configuration.

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under BizApp Connection, select Oracle Essbase and the GroundRunner to use with the connector.
   
3. Under Basic Info, enter a unique name and description to help identify the connection.
4. Under Properties, enter the connector's details:
   
   

   Property	Details
   User name	Enter the username of the connector's Essbase integration user.
   Password	Enter the password for the User Name property.
   Instance URL	Enter the base URL for the Essbase instance to connect to, including the leading protocol; often, an IP address such as http://100.0.0.1.
   Cluster name	Enter the Essbase cluster to connect to; by default, EssbaseCluster.
   Java API path	Enter the path to the client JAR files for the Essbase instance: If the GroundRunner and Essbase are installed on the same server, enter the path to the JAR files in the Essbase installation. If the GroundRunner and Essbase are installed on different servers, enter the path to the folder on the GroundRunner's server that contains copies of the JAR files.
   Embedded mode enabled	If the Essbase instance has Embedded Mode enabled, check this box. Note: Standalone Oracle Hyperion® environments typically have Embedded Mode enabled.

   Note: All sensitive credentials are automatically encrypted and stored at Advanced Encryption Standard (AES)-256 encryption.

5. Select the environments to use with the connection, and click Save.
6. To test the connection, create and run a chain with the connector's List Applications command, and verify it returns a valid output.

Troubleshooting

If the connection to Oracle Essbase fails:

• Verify the authentication credentials of the Essbase integration user.
• Check the GroundRunner selected for the connector.
• Check the base URL for the Essbase instance to connect to.
• Check the name of the Essbase cluster to connect to.
• Check the path to the Essbase client JAR files. If the GroundRunner is installed on a different server than the Essbase instance, ensure the JAR files are copied to the GroundRunner's server, and the path to the copies are entered as the connector's Java API Path property.
• Check the file extension of your uploaded file

If you experience an issue when running an Essbase connector command: 

No output received when running a command

If an Essbase command executes but the output is blank, install a compatible Java Runtime Environment (JRE), such as Oracle JRE 1.8.x.

Receive a Java "No Class Found" error

If you receive "Exception in thread "main" [] false} stdErr="java.lang.NoClassDefFoundError: com/essbase/api/base/EssException"", verify the JAR files are properly installed and configured in the connection.

Can't connect to Provider Server

If you receive "Error: com.essbase.api.base.EssException: Cannot connect to Provider Server. Make sure the signon parameters are correct and the Provider Server is running. Error authenticating with Essbase: Cannot connect to Provider Server. Make sure the signon parameters are correct and the Provider Server is running.":

• Ensure the specified server name is correct and is the provider server. Use the IP address and port number of your Essbase server only if they're on the same operating environment.
• Ensure that the specified port number is correct. By default, the port for APS is 19000.

Can't connect to Online Analytical Processing (OLAP) Service

If you receive "Error: com.essbase.api.base.EssException: Cannot connect to olap service. Cannot connect to Essbase Server. Error:Essbase Error(1042003): Network Error [11001]: Failed to retrieve name information for [Essbase-Cluster1] Error authenticating with Essbase: Cannot connect to olap service. Cannot connect to Essbase Server. Error:Essbase Error(1042003): Network Error [11001]: Failed to retrieve name information for [Essbase-Cluster1]", ensure the connection's Cluster Name is correct.

Cannot create olap file object

If you receive "Cannot create olap file object. Essbase Error(1030014): Invalid object type passed to ESSAPI function" then you should check that your uploaded file is in a supported format.

Natively supported filetypes will maintain their original file extension through the upload, while unsupported or unknown filetypes are changed to a .txt extension. This aides validation when passing the file to Essbase, but natively supported filetypes are preferred.