Upgrading to Java 7 for EPM 11.1.2.4 – It Doesn’t Need to be Difficult

As the end-of-life date for Oracle’s Extended Support of Java 6 approaches in December 2018, on-premises Hyperion EPM users have another deadline on their hands to be concerned with.

The Situation

First, some background information to put this post into proper context.

All Oracle EPM / Hyperion systems in the 11.1.2.x on-premises series of releases have Java SE 6 and JRockit 6 bundled with the software.  Oracle KB article # 2244851.1 states that both Java SE 6 and JRockit 6 will be coming out of Extended Support in December 2018; no new security patches will be issued for Java 6 & JRockit 6 beyond that date.  (Disclaimer: I’m not an Oracle employee and do not speak on behalf of Oracle Corporation)

In mid-June 2018, Oracle published KB article # 2351499.1, “How to Configure an Existing EPM 11.1.2.4 With Java 7,”.  This article contains two crucial pieces of information:

1. That EPM 11.1.2.4 is certified for Java SE 7, which replaces both Java SE 6 and JRockit 6.
2. A detailed technical procedure on how to manually update the system configuration accordingly.

When I first read through the article, the steps made sense… but what a tedious, manual process!  I was dreading having to do it for multiple customer systems, inevitably committing human error along the way, and then spending extra time figuring out what went wrong.

The Solution

What we need here is automation to streamline the process, so let’s get to it!  The process I’m about to describe was written for Windows-based systems, but could easily be adapted to a UNIX shell script as well.

• SwapJava.bat – This is our main wrapper script that guides us through the process.
• RecursiveReplace.ps1 – This Powershell script is used behind the scenes to recursively descend through a folder structure and replace any arbitrary text specified.  There are tools such as UltraEdit that do this, but I wanted to script the whole thing.
• sed.ps1 – This Powershell script is very similar to RecursiveReplace.ps1, except here we are editing a single file at a time.
• ScriptEnv.bat – This defines environment variables that I leverage across my entire suite of scripts; SwapJava.bat only needs a handful of them.

We double-click SwapJava.bat and it does the heavy lifting. The things you have to do yourself are:

• Download and install Java into the location suggested by the messages you see from SwapJava.bat.
• Export the Hyperion Solutions section from the Windows Registry.
• Import the Hyperion Solutions .reg file once SwapJava.bat finishes manipulating it.
• Inspect essbase.cfg, to see if anybody customized the jvm setting.
• Import your Root and Intermediate certificates into JDK 7’s cacerts file, if you had previously configure the system for SSL.

The Code

Want to see the code?  Read on!

August 4, 2018 update – if you downloaded my scripts previously, please re-download SwapJava.bat and sed.ps1, and both have been modified since the original post.

SwapJava.bat

@ECHO off
REM SwapJava.bat
REM
REM This script provides a guided process on replacing Oracle EPM's JDK 1.6 and JRockit 6
REM with Java 7.  Oracle has certified only EPM 11.1.2.4 to use Java 7 behind the scenes.
REM All older versons of EPM will need to remain on JDK 1.6 and JRockit 6 until the EPM
REM system is upgraded to EPM 11.1.2.4.0 or higher.
REM
REM This script must be executed on each EPM server.
REM
REM Other required scripts:
REM ScriptEnv.bat, sed.ps1 and RecursiveReplace.ps1
REM
REM This script is based upon instructions provide by Oracle on how to manually replace Java:
REM "How to Configure an Existing EPM 11.1.2.4 With Java 7" (Doc ID 2351499.1)
REM
REM  Written 07/04/2018 by Dave Shay (Datavail)
REM Modified 07/30/2018 by Dave Shay - Additional edit-replace operations in hyperion.reg.
REM Modified MM/DD/YYYY by Your Name - Briefly list changes made

CALL D:\Scripts\ScriptEnv.bat

ECHO --------------------------------------------------
ECHO This is a guided process to replace JDK SE 1.6 and JRockit 6 with JDK SE 7.
ECHO This process is only certified for EPM 11.1.2.4.0 and higher.
ECHO
ECHO Please shut down all EPM services, including the WebLogic Admin Server now.
PAUSE

ECHO Please install 64-bit JDK SE 1.7 (JDK7u181 or higher) now.
ECHO Override the suggested installation directory to:
ECHO %HYPDRIVE%\Oracle\Middleware\jdk7
ECHO You may click Cancel when prompted to install the public JRE.
ECHO Once installed, you can zip up the jdk7 folder and copy it to the other servers.
PAUSE

ECHO Now launch REGEDIT and export HKEY_LOCAL_MACHINE\SOFTWARE\Hyperion Solutions
ECHO and save the file as:
ECHO %SCRIPTDIR%\hyperion.reg
ECHO If this server runs Essbase only, the registry might not
ECHO contain a Hyperion Solutions hierarchy.
PAUSE

ECHO We're going to attempt to run an unsigned Windows PowerShell script now.
ECHO If you an error message in red, get assistance from your IT department
ECHO to temporarily alter the security policy on the EPM servers.
powershell.exe Set-ExecutionPolicy Unrestricted

ECHO If you got the error, please fix it now before proceding further.
PAUSE

ECHO Applying fixes to your exported hyperion.reg file....
COPY %SCRIPTDIR%\hyperion.reg %SCRIPTDIR%\hyperion.java6backup
powershell.exe %SCRIPTDIR%\sed.ps1 -file %SCRIPTDIR%\hyperion.reg -old jrockit_160_37\\jre\\bin\\jrockit\\jvm.dll -new jdk7\\jre\\bin\\server\\jvm.dll
powershell.exe %SCRIPTDIR%\sed.ps1 -file %SCRIPTDIR%\hyperion.reg -old JROCKI~2\\lib\\tools.jar -new jdk7\\lib\\tools.jar
powershell.exe %SCRIPTDIR%\sed.ps1 -file %SCRIPTDIR%\hyperion.reg -old jrockit_160_37 -new jdk7
powershell.exe %SCRIPTDIR%\sed.ps1 -file %SCRIPTDIR%\hyperion.reg -old jdk160_35 -new jdk7

ECHO Now please double-click %SCRIPTDIR%\hyperion.reg, and click Yes when prompted.
PAUSE

ECHO Backing up and editing setJavaRuntime.bat....
COPY %EPM_MW_HOME%\common\config\11.1.2.0\setJavaRuntime.bat setJavaRuntime.java6
powershell.exe %SCRIPTDIR%\sed.ps1 -file %EPM_MW_HOME%\common\config\11.1.2.0\setJavaRuntime.bat -old jdk160_35 -new jdk7

ECHO Backing up and editing setDomainEnv.cmd....
ECHO This file might not exist on an Essbase server, and that's OK.
SET DOMAINHOME=%HYPDRIVE%\Oracle\Middleware\user_projects\domains\EPMSystem
COPY %DOMAINHOME%\bin\setDomainEnv.cmd setDomainEnv.java6
powershell.exe %SCRIPTDIR%\sed.ps1 -file %DOMAINHOME%\bin\setDomainEnv.cmd -old jrockit_160_37 -new jdk7

ECHO Backing up and editing deploymentScripts....
ECHO The edit we're doing here assumes FlightRecorder is turned off.
ECHO If someone previously enabled FlightRecorder for monitoring purposes,
ECHO this edit/replace operation might not work propertly, and you may
ECHO need to manually add to your JAVA_OPTIONS:
ECHO -XX:-UnlockCommercialFeatures
SET DEPDIR=%EPM_INSTANCE_HOME%\bin\deploymentScripts
MKDIR %DEPDIR%\Backup
COPY %DEPDIR%\*.bat %DEPDIR%\Backup\
powershell.exe %SCRIPTDIR%\RecursiveReplace.ps1 -editDir %DEPDIR% -old '-XX:-FlightRecorder' -new '-XX:-UnlockCommercialFeatures -XX:-FlightRecorder'
PAUSE

ECHO Don't worry if the next step produces an error message.
ECHO Here, we are backing up and editing a file that only exists on an Essbase server.
COPY %EPM_INSTANCE_HOME%\config\OPMN\opmn\opmn.xml %EPM_INSTANCE_HOME%\config\OPMN\opmn\opmn-java6
powershell.exe %SCRIPTDIR%\sed.ps1 -file %EPM_INSTANCE_HOME%\config\OPMN\opmn\opmn.xml -old jdk160_35 -new jdk7
PAUSE

ECHO If this an an Essbase server, please now inspect the essbase.cfg file, usually located here:
ECHO %EPM_INSTANCE_HOME%\EssbaseServer\essbaseserver1\bin\essbase.cfg
ECHO If the line containing the text "JvmModuleLocation" does not begin with a semicolon ";"
ECHO then you will need to manually change it to
ECHO %EPM_MW_HOME%\jdk7\jre\bin\server\jvm.dll
PAUSE

ECHO Don't worry if the next step produces an error message.
ECHO This step applicable on the EPMA Server host only.
COPY %EPM_INSTANCE_HOME%\config\EPMA\BPMA_Server_Config.xml %EPM_INSTANCE_HOME%\config\EPMA\BPMA_Server_Config.java6
powershell.exe %SCRIPTDIR%\sed.ps1 -file %EPM_INSTANCE_HOME%\config\EPMA\BPMA_Server_Config.xml -old jdk160_35 -new jdk7
PAUSE

ECHO Don't worry if the next step produces an error message.
ECHO This step applicable if the EAS Console was installed.
COPY %EPM_MW_HOME%\products\Essbase\eas\console\bin\admincon.bat %EPM_MW_HOME%\products\Essbase\eas\console\bin\admincon.java6
powershell.exe %SCRIPTDIR%\sed.ps1 -file %EPM_MW_HOME%\products\Essbase\eas\console\bin\admincon.bat -old jdk160_35 -new jdk7
PAUSE

ECHO And now likewise for the Financial Reporting Studio thick client....
COPY %EPM_MW_HOME%\products\financialreporting\bin\setJavaRuntime.cmd %EPM_MW_HOME%\products\financialreporting\bin\setJavaRuntime.java6
powershell.exe %SCRIPTDIR%\sed.ps1 -file %EPM_MW_HOME%\products\financialreporting\bin\setJavaRuntime.cmd -old jdk160_35 -new jdk7
PAUSE

ECHO --------------------------------------------------
ECHO Final step!  If your system was previously configured for SSL,
ECHO the Root and Intermediate certificates need to be imported into:
ECHO %HYPDRIVE%\Oracle\Middleware\jdk7\jre\lib\security\cacerts
ECHO Restart services and start testing!
ECHO --------------------------------------------------
PAUSE

RecursiveReplace.ps1

# RecursiveReplace.ps1
#
# This Powershell script recursively replaces all references of text within
# a directory hierarchy.  If the specified directory contains subdirectories,
# it will recursively descend into all subdirectories and repeat the process.
#
# Syntax:  powershell D:\Scripts\RecursiveReplace.ps1 -editDir <directory name> -old '<old text>' -new '<new text>'
# Example: powershell D:\Scripts\RecursiveReplace.ps1 -editDir D:\import_export\ExportSharedServices -old EssbaseCluster-1 -new 'Prod Essbase'
#
# If the values supplied to either -old or -new must contain spaces,
# then those values should be enclosed with single quote (') characters.
#
# If you receive a security policy error about “unsigned” Powershell scripts when
# running this process, open a command prompt and type:
# powershell.exe Set-ExecutionPolicy Unrestricted
#
#  Written on 04/09/2015 by Dave Shay (Datavail)
# Modified on MM/DD/YYYY by Your Name - Briefly describe changes

param($editDir, $old, $new)

# $editFiles=Get-ChildItem $editDir * -Recurse
$editFiles=Get-ChildItem $editDir -Recurse | Where-Object{!($_.PSIsContainer)}

foreach ($file in $editFiles)
{
if(Select-String $file.PSPath -pattern "$old")
{
Write-Host Found matching text within $file.FullName

(Get-Content $file.PSPath) |
Foreach-Object {$_ -replace "$old", "$new"} |
Set-Content $file.PSPath
}
}

sed.ps1

# sed.ps1
#
# This Powershell script replaces all references of text within
# a specified file.
#
# Syntax:  powershell D:\Scripts\sed.ps1 -file  -old '' -new ''
# Example: powershell D:\Scripts\sed.ps1 -file D:\Scriipts\Hyperion.reg -old jdk160_36 -new jdk7
#
# If the values supplied to either -old or -new must contain spaces,
# then those values should be enclosed with single quote (') characters.
#
# If you receive a security policy error about “unsigned” Powershell scripts when 
# running this process, open a command prompt and type:
# powershell.exe Set-ExecutionPolicy Unrestricted
#
#  Written on 07/04/2018 by Dave Shay (Datavail)
# Modified on 07/30/2018 by Dave Shay - Added the SimpleMatch parameter and simplified
#    the text replacement command.
# Modified on MM/DD/YYYY by Your Name - Briefly describe changes

param($file, $old, $new)

if(Select-String -SimpleMatch -Path $file -pattern $old)
{
    Write-Host Found matching text within $file
   
    (Get-Content $file).replace($old, $new) | Set-Content $file
}

ScriptEnv.bat
(The file I use is larger… here I am just revealing the variables used by SwapJava.bat)

@echo off
REM ScriptEnv.bat
REM
REM This script is called by most of the other automation scripts and utilities
REM written by Datavail's EPM practice.  Modify the variable values below
REM as appropriate for your environment.
REM
REM  Written on 04/18/2015 by Dave Shay (Datavail)
REM Modified on MM/DD/YYYY by Your Name - Briefly list changes made

REM Modify the values below as appropriate for your environment, but
REM do not change the names of the variables.

Set EPM_INSTANCE_NAME=epmsystem1
Set HYPDRIVE=D:
Set EPM_INSTANCE_HOME=%HYPDRIVE%\Oracle\Middleware\user_projects\%EPM_INSTANCE_NAME%
Set EPM_MW_HOME=%HYPDRIVE%\Oracle\Middleware\EPMSystem11R1
Set SCRIPTDIR=%HYPDRIVE%\Scripts

Conclusion

With these scripts in hand, you can get through the process quickly, and with less human error.

If you’re not comfortable doing this yourself, reach out to me on LinkedIn or contact a Datavail sales executive, and we can get a conversation started.

Best of luck out there!