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 choose both the target servlet container and the version of the Essbase Java API files to use. The connector ships with several Essbase versions, and additional ones can be added as needed. Each version must have its own folder in the drivers folder.

The deployment target determines which servlet API namespace is packaged:

Target option Servlet namespace Connector payload

weblogic-14

javax.servlet

Frozen connector 1.0 compatibility payload

tomcat-9

javax.servlet

Frozen connector 1.0 compatibility payload

weblogic-15

jakarta.servlet

Current connector 1.1 payload

tomcat-10

jakarta.servlet

Current connector 1.1 payload

Using a command prompt, navigate into the /tools subdirectory of the connector distribution. For example, the following command builds a WebLogic 15 WAR using Essbase 11.1.2.4.048 media:

java -jar dodeca-essbase-packager.jar create --target weblogic-15 --version 11.1.2.4.048

For WebLogic 14, use --target weblogic-14. The packager creates a file named dodeca-essbase.war in the same folder. Deploy this file normally to the selected Tomcat or WebLogic instance. Do not build for one target and deploy to another namespace generation.

The published connector distribution contains both payload generations. When building the distribution from source, supply the official connector 1.0.0 distribution with -Dlegacy.distribution.zip=/path/to/dodeca-essbase-connector-1.0.0.zip to include the frozen Javax payload. The release workflow downloads that asset and verifies its checksum before packaging it.

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. If the folder you copied contains an essbase.properties file, the service ignores it there — edit config/essbase.properties instead.

  2. Confirm that Java version 17 or newer 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 "17.0.16" 2025-07-15
 OpenJDK Runtime Environment Temurin-17.0.16+8 (build 17.0.16+8)
 OpenJDK 64-Bit Server VM Temurin-17.0.16+8 (build 17.0.16+8, 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

Adjusting Essbase Java API Settings (essbase.properties)

The Essbase Java API reads optional settings from a file named essbase.properties. A common example is working around timeouts on long-running Essbase operations:

olap.server.netSocketTryInfinite=true

Where to edit the file depends on your deployment:

  • Standalone: edit config/essbase.properties and restart the service.

  • WAR: the packager places an essbase.properties in WEB-INF/classes of the WAR. If the Essbase media folder used to build the WAR contains its own essbase.properties, that copy is used; otherwise the packager adds a default template. To change a setting, copy config/essbase.properties into your media folder (for example drivers/21.5.1.0.0.016/essbase.properties), edit it, and rebuild the WAR.

On startup, the connector logs the essbase.properties visible on its classpath:

Essbase properties file in use for embedded mode: ...

If the log shows (none), no essbase.properties is on the classpath.

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 1.1.0

  • Requires Java 17 or newer for the standalone connector.

  • Uses Jakarta Servlet and JAXB APIs for WebLogic 15 and Tomcat 10 deployments.

  • Retains a frozen connector 1.0 payload for WebLogic 14 and Tomcat 9 WAR deployments.

  • Requires an explicit deployment target when building a WAR.

  • Fixed an issue where view builds using a stateless Essbase connection failed with the error "Invalid session ID. One possibility is that the server may be restarted. Sign off and sign on again." when connecting to Essbase 21.8.2 or higher. The connector now applies the user locale to the Essbase session after sign on and quietly continues without a locale when the server rejects it. #4557

  • Fixed an issue where privilege errors on connections using impersonation named the admin user that established the session, for example "User [weblogic] does not have sufficient privileges to perform this operation", instead of the impersonated user. Privilege errors from Essbase operations now name the impersonated user, and a privilege error during sign on is reported as a rejected sign-on with the server’s error code, because the server can report a transient sign-on failure with the same privilege text. The original server text is written to the connector log. #4498

  • Fixed an issue where an operation on a connection using impersonation could intermittently fail with an insufficient privilege error when the connector read cube information for a cube with typed measures enabled. The smart lists and date format string needed for typed measure support are now included in the cube information. #4584

Version 1.0.0

  • Fixed Issue: When sending data to an Essbase application whose name contains an ampersand (&) or other character that requires, a deserialization error occurs. #3897

Version 8.4.5

  • Added 21.7.3.0.0.010 Essbase jars, removed 11.1.2.4 series Essbase jars except 11.1.2.4.048.

Version 8.4.4

  • There are no changes in this version. Moving forward, the Dodeca Essbase Connector will maintain its own versioning separate from the main Dodeca product.

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