Oracle Customer Engineering & Advocacy Lab (CEAL) Blog covers Oracle Analytics Cloud, Oracle Analytics Server and...

A Simple Guide to HFM Java API

Marc Schumacher
Principal EPM/OBI Infrastructure Engineering Specialist - Customer Engineering & Advocacy Lab (CEAL Team)
Oracle EPM is available since quite a while now. A lot of customers have adopted this release and start looking into automating common tasks to further increase the user experience and lower the maintenance efforts. Using the Java API, common HFM tasks can be automated easily. This post will provide first steps to log into HFM and run a Consolidation using the Java API.

In an earlier blog post, I described the HFM Architecture.

Some may remember, that one of the changes was in regards to HFM components (e.g. HFM Web, HFM application server) communicating with each other. In previous releases Microsoft DCOM was used, which was replaced by a more common communication system that can be used across operating systems. This is the reason why the old Visual Basic or Visual Basic Script do not work anymore.

Oracle published a “Developer and Customization Guide” as part of the “Oracle Enterprise Performance Management System Documentation”. While this documentation even describes how to setup Oracle JDeveloper to get started with the HFM Java API, this post will just cover a small example as well as the information on how to setup the environment to run HFM API programs without setting up JDeveloper on the server.

The full example can be downloaded here.

Lets look into the different sections of the code ignoring the import section at the top. After reading the System Properties into variables a verification is done to check, if all required Java System properties and command line options exist. Otherwise the program exists after showing usage instructions.

public class runConsol{
    // Read System properties into variables
    static String EPM_ORACLE_INSTANCE = System.getProperty("EPM_ORACLE_INSTANCE");
    static String HFM_CLUSTER = System.getProperty("HFM_CLUSTER");
    static String HFM_APPLICATION = System.getProperty("HFM_APPLICATION");

    static private String ssoToken;
    static private SessionOM sessionOM;

    public static void main(String[] args) throws HFMException {
        // Check if all System properties and arguments are set
        if(args.length != 4 || EPM_ORACLE_INSTANCE == null || HFM_CLUSTER == null || HFM_APPLICATION == null || (!args[2].equals("1") && !args[2].equals("2") && !args[2].equals("3") ) ) {
                System.out.println("Usage: java -DEPM_ORACLE_INSTANCE=<pathToOracleEPMInstance> -DHFM_CLUSTER=<HFMClustername> -DHFM_APPLICATION=<HFMApplicationname> runConsol <USER> <PASSWORD> <ConsolidationType> <POV>"); 
                System.out.println("  With <ConsolidationType>: 1 - Consolidate (Impacted)  2 - Consolidate All with Data  3 - Consolidate All");

User name, password, the consolidation type and the point of view, which are command line arguments are stored into variables:

        String username = args[0];
        String password = args[1];
        int consolidationType = Integer.parseInt(args[2]);
        String pov = args[3];

        switch ( consolidationType ) {

Afterwards an Oracle EPM Session is created:

        try {
            Map context = new HashMap(5);
            CSSSystem system = CSSSystem.getInstance(context, EPM_ORACLE_INSTANCE);
            CSSAPIIF css = system.getCSSAPI();
            CSSUserIF user = css.authenticate(context, username, password);
            ssoToken = user.getToken();
        } catch (CSSException e) {

This is followed by the creation of a session in HFM:

        try {
                sessionOM = new SessionOM();
                SessionInfo session = sessionOM.createSession(ssoToken, Locale.ENGLISH, HFM_CLUSTER, HFM_APPLICATION);

And finally the launch of the Consolidation:

                DataOM dataOM = new DataOM(session);
                List<String> povs = new ArrayList<String>(1);
                System.out.println("Running consolidation with POV: " + pov);
                ServerTaskInfo taskInfo = dataOM.executeServerTask(consolidationTypeString, povs);

Obviously, we need to close our session after we are done:

        } catch (HFMException e) {

Now we have a rough idea what the code does, but how can we run the program?

Before even running the Java compiler, the environment needs to be setup, so the compiler as well as the Java Virtual Machine can find all required libraries and environmental information. Here are scripts for Unix and Windows environments, which can be used to setup the environment.

Download the script to setup the environment on UNIX.

Download the script to setup the environment on Windows.

Make sure you change the ORACLE_MIDDLEWARE_HOME variable in the first line according to the path in your environment.

After the environment is setup, Java bytecode can be generated running the compiler. The syntax is slightly different on Windows and Unix.

Windows: javac -cp %EPM_JAVA_CLASSPATH% runConsol.java

UNIX:    javac -cp $EPM_JAVA_CLASSPATH runConsol.java

Now you can launch a Consolidation using the HFM Java API.





Make sure you run the above command on a single line without any line breaks.

While the Consolidation is running the progress can be followed in the applications “Running Tasks” screen.

Join the discussion

Comments ( 5 )
  • Arunachalam Somasundaram Friday, January 19, 2018
    Should it be possible to authenticate with username / password using HFM Java API where the environment uses SSO with Oracle Access Manager? Or is the HFM Java API not compatible with this style of authentication?
  • Marc Schumacher Friday, January 26, 2018
    Yes, you can authenticate with username/password using the HFM API, if SSO is configured.

    SSO will only be used for users accessing the Oracle EPM through the web interface.
  • Prasad Wednesday, October 2, 2019
    Simple and superbly explained. Thanks Marc.
  • Daniel Wednesday, November 20, 2019
    Hi. Sorry for the question.
    I need to know where I can download the JARs to run this example.
    I found a lot of files to download but I have never found the right libraries to run this example.
  • Marc Schumacher Friday, November 29, 2019
    All jar files are included in the HFM Server install, you do not need to download those files separately.
    The setup environment scripts provided, tell you where those files are located on the disk.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.