Dodeca Essbase Connector

This package contains all files needed to run and deploy the Dodeca Essbase Connector. Historically, this connector has also been referred to as the "Essbase servlet". As of version 8.4, this connector is now packaged as a combined build that contains both the "standalone" version of the Dodeca Essbase Connector in addition to files and tooling needed to build a WAR file that can be deployed in a servlet container such as Apache Tomcat or Oracle WebLogic.

You can choose to use either the standalone or the WAR version of deployment. They are functionally the same once deployed. Standalone:

  • Can be easily installed as a Windows or Linux service

  • Outputs logs to a single location (/logs/)

  • Runs by default on port 8252

The traditional WAR deployment:

  • Can be placed into an Apache Tomcat or Oracle WebLogic instance

  • The servlet container handles logging

  • Requires you to build a .war file for your version of Essbase

  • Runs on the port that your servlet container uses (usually 8080 or 9000)

Building a .WAR File

At a minimum, you need to decide which version of the Essbase Java API files to use. The connector ships with several to choose from, and additional ones can be added as needed. Versions include 11.1.2.4.048, 21.5.1.0.0.016, and more. Each version must have its own folder in the drivers folder.

Then, using a command prompt, navigate in to the /tools subdirectory of in the connector distribution. Run the following command to build a .war file for your version of Essbase:

java -jar dodeca-essbase-packager.jar create --version 11.1.2.4.048

The packager will then create a .war file named dodeca-essbase.war in the same folder. You can deploy this file as normal to your Tomcat/WebLogic instance.

Adding Additional Essbase Media

Simply create a folder in the drivers folder named for the exact version of Essbase media you want to use. For example, if there is a new patch to the 11.1.2.4 series such as 11.1.2.4.099, create a folder named that and place the Essbase JAR files in there. At a minimum, you need to have an ess_japi.jar file, although depending on your usage you may need the related ess_es_server.jar, cpld.jar, ojdl.jar and other files.

Deploying the Standalone Version of the Connector

a standalone version of the Dodeca Essbase connector, meaning that it runs as its own service and does not require being dropped into an existing Tomcat/WebLogic instance. Steps to setup:

  1. You must choose a version of the Essbase Java API files to use. Generally you should match up your version of Essbase files to your exact server. For example, if you are running an 11.1.2.4.042 server, then you would choose the corresponding files from the /drivers folder. In order to set your version of the Essbase Java API, copy the entire folder you want to use, then rename it to current. For example, you should end up with a folder inside of drivers named current that contains the proper Java jar files. E.g. your drivers/current folder will contain ess_japi.jar, ess_es_server.jar, cpld.jar, and ojdl.jar if you started with the 11.1.2.4.042 folder. Other version sets may have slightly different sets of files.

  2. Confirm that Java version 8 is on the PATH, by running java -version on the command line. You should see output like the following:

     C:\Users\test>java -version
    
     openjdk version "1.8.0_242"
     OpenJDK Runtime Environment (Zulu 8.44.0.11-CA-win64) (build 1.8.0_242-b20)
     OpenJDK 64-Bit Server VM (Zulu 8.44.0.11-CA-win64) (build 25.242-b20, mixed mode)
  3. You should now be able to navigate to the /bin folder and run dodeca-essbase-connector.bat console (if using Windows) or the non-suffixed file if on Linux. You should see the connector startup. When the connector starts up, you can confirm that it is running by visiting this URL:

     http://localhost:8252/dodeca-essbase/Servlet

    You can confirm that the service is accessible from remote computers by attempting to access the same URL, substituting the server name for localhost.

  4. After confirming that the service starts successfully in console mode, you may wish to install as an actual Windows service. To do so, open up a Command prompt in Administrator mode (e.g. search for cmd, then right-click and select Run as Administrator, then navigate to the bin folder in your Dodeca Essbase connector location and type the following:

     dodeca-essbase-connector install

    This should install the service (you can confirm by looking at your list of Windows Services and seeing a new entry for Dodeca Essbase Connector). You can start it from there or use this command to start the service from the command line:

     dodeca-essbase-connector start

Using the Encryption Utility

The Essbase Connector includes an encryption utility in the tools directory that can be used to generate encrypted values for passwords in your Tomcat’s server.xml file.

Encrypting a Password

To encrypt a password:

java -jar tools/dodeca-essbase-encrypter.jar --encrypt "your_password"

Decrypting a Value

To decrypt an encrypted value (for verification):

java -jar tools/dodeca-essbase-encrypter.jar --decrypt "encrypted_value"

The encrypted values can be used directly in your Tomcat’s server.xml file JNDI password fields.

Release Notes

Version 8.4.4

Version 8.4.1

  • Fixed Issue: The absence of the JAXB-API XML parsing libraries in the default Java distribution (starting with Java 11) caused errors in the Essbase Connector. The JAXB-API library is now included in the Essbase Connector distribution, preventing users from encountering the following error: Implementation of JAXB-API has not been found on module path or classpath. #3913

Version 8.4.0

  • Fixed Issue: When a blank value is sent during a send operation, an error message stating "Cell content is not double." is displayed. #3892

  • The Dodeca Essbase Connector (WAR packaging) and Dodeca Essbase Standalone Connector have been merged into a single distribution. Instead of shipping pre-packaged .WAR files for each version of Essbase Java media, the media are provided and a packager tool has been shipped with the standalone connector that will generate a .WAR file for a given version of Essbase media. The packager tool is provided in the /tools folder of the connector. The simplest possible invocation is to run java -jar dodeca-essbase-packager.jar create --version 11.1.2.4.048 which would then create a WAR file containing the Essbase Java media for version 11.1.2.4.048. #3468

  • The Tanuki Java Service Wrapper, which is used to manage the Dodeca-Essbase Standalone service, was updated from version 3.2.3 to version 3.5.54. #3863

Version 8.3.6

  • Fixed Issue: When sending data to Essbase, under some circumstances, an error similar to the following can occur: Unable to perform Essbase update operation. Lock requested by user [<user>] is currently held by another user [<user>] performing [ActionNotFound], and waiting is currently not allowed. Requested block is [[<member>][…]]. This issue was introduced in 8.3.0. #3766

  • Fixed Issue: Data audit log records are not created when sending data to missing cells or cells containing date or text measures. #3743

Version 8.3.2

  • Security Fix: The version of the spring-beans Java library has been upgraded to 5.3.27 to remediate CVE-2022-22965. #3509

Version 8.3.0

  • Fixed Issue: When the Essbase Connector is used in APS mode, the Essbase server’s APS logs may contain one or more errors similar to the following:

    java.io.InvalidClassException: com.appliedolap.dodeca.essbase.server.connection.EssbaseMessageHandler; Essbase JAPI - unauthorized deserialization

    java.lang.ClassNotFoundException: com.appliedolap.dodeca.essbase.server.connection.EssbaseMessageHandler

    This issue is caused by APS not having the Essbase Connector’s EssbaseMessageHandler class in its classpath. In 8.3, the Essbase Connector does not write custom messages when used in APS mode. #3409, #3459

Version 8.0.4

  • Fixed Issue: The 8x Dodeca Essbase Connector fails to deploy successfully in Websphere. #2992