Recreate an Old EPM Cloud Environment for Audits
Use the script in this section to create a self-service solution to maintain an up-to-date library of snapshots for your Oracle Enterprise Performance Management Cloud environment. You require an environment dedicated for the purpose of upgrading and maintaining a library of up-to-date snapshots.
EPM Cloud supports snapshot compatibility for one monthly cycle only; you can migrate maintenance snapshots from the test environment to the production environment and vice versa. However, the auditing requirements of some customers may necessitate restoring snapshots from multiple years on the latest environment, and accessing application in a short period of time.
You should schedule this script to run once every month to convert the available snapshots and make them compatible with the latest EPM Cloud patch level. Oracle recommends that you run the script after the third Friday of the month to ensure that all issues within the production environment have been resolved.
Note:
You cannot use this script to update Narrative Reporting, Account Reconciliation, and Oracle Enterprise Data Management Cloud snapshots.
How the Script Works
For every snapshot stored by the customer, the upgrade script completes these tasks using EPM Automate :- Using the information in the
input.properties
file, logs into an environment - Uses the
recreate
command to refurbish the environment - Imports the snapshot into the environment
- Runs daily maintenance on the environment, which results in the snapshot being converted into the format compatible with the current EPM Cloud patch level.
- Downloads
Artifact Snapshot
(the maintenance snapshot) into a folder. If you re-created an 18.05 environment by uploading snapshots fromsnapshots/18.05
,Artifact Snapshot
is downloaded intosnapshots/18.06
. - Emails the results of recreating old environments to an email address, if specified.
Running the Script
- Create the
input.properties
file and update it with information for your environment. Save the file in a local, directory. This directory, referred to asparentsnapshotdirectory
in this discussion. Contents of this file differs depending on your operating system.Make sure that you have write privileges in this directory. For Windows, you may need to start PowerShell using the Run as Administrator option to be able to run scripts.
- Create
upgradeSnapshots.ps1
(Windows PowerShell) orupgradeSnapshots.sh
(Linux/UNIX) script and save it in theparentsnapshotdirectory
whereinput.properties
is located. - Create a sub-directory, for example,
snapshots
, within theparentsnapshotdirectory
. - Within the directory that you created in the preceding step (
snapshots
), create a sub-directory for the monthly snapshot that you want to convert to make it compatible with the current EPM Cloud patch level. Name the directory using theYY.MM
format; for example,18.05
for the directory to store the May 2018 snapshots. - Copy snapshots into the appropriate sub-directory. For example, copy the snapshots for May 2018 into
snapshots/18.05
. - Launch the script.
- Linux/UNIX: run
./upgradeSnapshots.sh
. - Windows PowerShell: run
upgradeSnapshots.ps1
.
- Linux/UNIX: run
Windows
Create input.properties
and upgradeSnapshots.ps1
script by copying the scripts in this section.
Creating input.properties
username=exampleAdmin
userpassword=examplePassword
serviceurl=exapleURL
proxyserverusername=proxyServerUserName
proxyserverpassword=proxyPassword
proxyserverdomain=proxyDoamin
parentsnapshotdirectory=C:/some_directory/snapshots
emailtoaddress=exampleAdmin@oracle.com
Updating input.properties
Note:
If authentication at proxy server
is not enabled for your Windows network environment, remove the properties proxyserverusername
, proxyserverpassword
, and proxyserverdomain
from the input.properties
file.
Table 3-9 input.properties Parameters
Parameter | Description |
---|---|
username |
User name of a Service Administrator. |
userpassword |
Password of the Service Administrator . |
serviceurl |
URL of the environment that is used for this activity. |
proxyserverusername |
The user name to authenticate a secure session with the proxy server that controls access to the internet. |
proxyserverpassword |
The password to authenticate the user with the proxy server. |
proxyserverdomain |
The name of the domain defined for the proxy server. |
parentsnapshotdirectory |
Absolute path of the directory that is to be used as the parent directory of the directory that stores the snapshots to be processed. Use forward slashes (/) as directory separators. |
emailtoaddress |
Optionally, the email address to which the results of recreating old environments are to be sent. The results are emailed only if this value is specified.
Example: |
Note:
If your password contains special characters, see Handling Special Characters.
Creating upgradeSnapshots.ps1
Use this sample script to create upgradeSnapshots.ps1
# Script for recreating an old EPM Cloud environment
# read in key/value pairs from input.properties file
$inputproperties=ConvertFrom-StringData(Get-Content ./input.properties -raw)
# Global variables
$parentsnapshotdirectory="$($inputproperties.parentsnapshotdirectory)"
$username="$($inputproperties.username)"
$userpassword="$($inputproperties.userpassword)"
$serviceurl="$($inputproperties.serviceurl)"
$proxyserverusername="$($inputproperties.proxyserverusername)"
$proxyserverpassword="$($inputproperties.proxyserverpassword)"
$proxyserverdomain="$($inputproperties.proxyserverdomain)"
$emailtoaddress="$($inputproperties.emailtoaddress)"
$operationmessage="EPM Automate operation:"
$operationfailuremessage="EPM Automate operation failed:"
$operationsuccessmessage="EPM Automate operation completed successfully:"
$epmautomatescript="epmautomate.bat"
$workingdir="$pwd"
$logdir="$workingdir/logs/"
$logfile="$logdir/epmautomate-upgradesnapshots.log"
function LogMessage
{
$message=$args[0]
$_mydate=$(get-date -f dd_MM_yy_HH_mm_ss)
echo "[$_mydate] $message" >> $logfile
}
function LogAndEchoMessage
{
$message=$args[0]
$_mydate=$(get-date -f dd_MM_yy_HH_mm_ss)
echo "[$_mydate] $message" | Tee-Object -Append -FilePath $logfile
}
function LogOutput
{
$_mydate=$(get-date -f dd_MM_yy_HH_mm_ss)
$op=$args[0]
$opoutput=$args[1]
$returncode=$args[2]
#If error
if ($returncode -ne 0) {
$failmessage="[$_mydate] $operationfailuremessage $op"
LogMessage $failmessage
LogMessage $opoutput
LogMessage "return code: $returncode"
} else {
$successmessage="[$_mydate] $operationsuccessmessage $op"
LogMessage $successmessage
LogMessage $opoutput
LogMessage "return code: $returncode"
}
}
function ExecuteCommand
{
$op=$args[0]
$epmautomatecall="$epmautomatescript $op"
$date=$(get-date -f dd_MM_yy_HH_mm_ss)
LogMessage "$operationmessage $epmautomatecall"
$operationoutput=iex "& $epmautomatecall" >> $logfile 2>&1
LogOutput $op $operationoutput $LastExitCode
}
function ProcessCommand
{
$command=$args[0]
$date=$(get-date -f dd_MM_yy_HH_mm_ss)
if (!([string]::IsNullOrWhitespace($command))) {
if (!($command.StartsWith("#"))) {
ExecuteCommand $command
}
}
}
function Init
{
$logdirexists=Test-Path $logdir
if (!($logdirexists)) {
mkdir $logdir 2>&1 | out-null
}
# removing existing epmautomate debug logs
rm ./*.log
$logfileexists=Test-Path $logfile
# remove existing log file
if ($logfileexists) {
rm $logfile
}
}
function GetNextDate
{
$latestyearmonth=$args[0]
LogMessage "latest year.month: $latestyearmonth"
$latestyear,$latestmonth=$latestyearmonth.split('\.')
LogMessage "latest year: $latestyear"
LogMessage "latest month: $latestmonth"
$intlatestyear=[int]$latestyear
$intlatestmonth=[int]$latestmonth
if ($intlatestmonth -eq 12) {
$intnextmonth=1
$intnextyear=$intlatestyear+1
} else {
$intnextmonth=$intlatestmonth+1
$intnextyear=$intlatestyear
}
$nextyear="{0:D2}" -f $intnextyear
$nextmonth="{0:D2}" -f $intnextmonth
echo "$nextyear.$nextmonth"
}
function ProcessSnapshot
{
$snapshotfile=$args[0]
LogMessage "snapshotfile: $snapshotfile"
$nextdate=$args[1]
LogMessage "nextdate: $nextdate"
$snapshotfilename=$snapshotfile.split('/')[-1]
LogMessage "snapshotfilename: $snapshotfilename"
$snapshotname=$snapshotfilename.split('.')[0]
LogMessage "snapshotname: $snapshotname"
ProcessCommand "login $username $userpassword $serviceurl $proxyserverusername $proxyserverpassword $proxyserverdomain"
ProcessCommand "recreate -f"
ProcessCommand "uploadfile $snapshotfile"
ProcessCommand "importsnapshot $snapshotname"
ProcessCommand "runDailyMaintenance skipNext=true -f"
ProcessCommand "downloadfile 'Artifact Snapshot'"
ProcessCommand "deletefile $snapshotname"
ProcessCommand "logout"
$nextdatedirexists=Test-Path $parentsnapshotdirectory/$nextdate
if (!($nextdatedirexists)) {
mkdir $parentsnapshotdirectory/$nextdate 2>&1 | out-null
}
LogMessage "Renaming 'Artifact Snapshot.zip' to $snapshotname.zip and moving to $parentsnapshotdirectory/$nextdate"
mv $workingdir/'Artifact Snapshot.zip' $workingdir/$snapshotname.zip >> $logfile 2>&1
mv $workingdir/$snapshotname.zip $parentsnapshotdirectory/$nextdate >> $logfile 2>&1
}
function callSendMail
{
$logfile=$logfile -replace "\\", "/"
$elements=$logfile.split('/')
$logfilename=$elements[-1]
if (${emailtoaddress} -match "@") {
epmautomate.bat login ${username} ${userpassword} ${serviceurl}
epmautomate.bat uploadFile "$logfile"
epmautomate.bat sendMail $emailtoaddress "Recreating An Old EPM Cloud Environment results" Body="The results of recreating an old EPM Cloud Environment are attached." Attachments=$logfilename
epmautomate.bat deleteFile "$logfilename"
epmautomate.bat logout
}
}
#----- main body of processing
date
Init
LogAndEchoMessage "Starting upgrade snapshots processing"
$snapshotdirs=@(Get-ChildItem -Directory "$parentsnapshotdirectory" -name)
LogMessage "snapshot directories: $snapshotdirs"
$latestreleasedate=$snapshotdirs[-1]
LogMessage "latest release date: $latestreleasedate"
$latestreleasesnapshotdir="$parentsnapshotdirectory/$latestreleasedate"
LogMessage "latest release snapshot dir: $latestreleasesnapshotdir"
$nextdate=$(GetNextDate "$latestreleasedate")
$snapshotfiles=@(Get-ChildItem -File "$latestreleasesnapshotdir")
if ($snapshotfiles.length -eq 0) {
LogAndEchoMessage "No snapshot files found in directory $latestreleasesnapshotdir. Exiting script."
exit
}
foreach ($snapshotfile in $snapshotfiles) {
LogAndEchoMessage "Processing snapshotfile: $snapshotfile"
ProcessSnapshot $latestreleasesnapshotdir/$snapshotfile $nextdate
}
LogAndEchoMessage "Upgrade snapshots processing completed"
date
callSendMail
Linux/UNIX
Create upgradeSnapshots.sh
and input.properties
by copying the following scripts.
Creating input.properties
for Linux/UNIX
Note:
If your network is not configured to use a proxy server to access the internet, remove the properties proxyserverusername
, proxyserverpassword
, and proxyserverdomain
from the input.properties
file.
username=exampleAdmin
userpassword=examplePassword
serviceurl=exapleURL
proxyserverusername=
proxyserverpassword=
proxyserverdomain=
jdkdir=/home/user1/jdk160_35
epmautomatescript=/home/exampleAdmin/epmautomate/bin/epmautomate.sh
parentsnapshotdirectory=/home/exampleAdmin/some_directory/snapshots
emailtoaddress=exampleAdmin@oracle.com
Updating input.properties
Table 3-10 input.properties Parameters
Parameter | Description |
---|---|
username |
User name of a Service Administrator. |
userpassword |
Password of the Service Administrator . |
serviceurl |
URL of the environment that is being used for this activity. |
proxyserverusername |
The user name to authenticate a secure session with the proxy server that controls access to the internet. |
proxyserverpassword |
The password to authenticate the user with the proxy server. |
proxyserverdomain |
The name of the domain defined for the proxy server. |
jdkdir |
JAVA_HOME location.
|
epmautomatescript |
Absolute path of EPM Automate executable (epmautomate.sh ).
|
parentsnapshotdirectory |
Absolute path of the directory that is to be used as the parent directory of the directory that stores the snapshot to be processed. |
emailtoaddress |
Optionally, the email address to which the results of recreating old environments are to be sent. |
Note:
If your password contains special characters, see Handling Special Characters.
Creating upgradeSnapshots.sh
Use this sample script to create upgradeSnapshots.sh
#!/bin/sh
. ./input.properties
workingdir=$(pwd)
logdir="${workingdir}/logs"
logfile=epmautomate-upgradesnapshots.log
operationmessage="EPM Automate operation:"
operationfailuremessage="EPM Automate operation failed:"
operationsuccessmessage="EPM Automate operation completed successfully:"
logdebugmessages=true
if [ ! -d ${jdkdir} ]
then
echo "Could not locate JDK/JRE. Please set value for "jdkdir" property in input.properties file to a valid JDK/JRE location."
exit
fi
if [ ! -f ${epmautomatescript} ]
then
echo "Could not locate EPM Automate script. Please set value for "epmautomatescript" property in the input.properties file."
exit
fi
export JAVA_HOME=${jdkdir}
debugmessage() {
# logdebugmessages is defined (or not) in testbase input.properties
if [ "${logdebugmessages}" = "true" ]
then
logmessage "$1"
fi
}
logmessage()
{
local message=$1
local _mydate=$(date)
echo "[$_mydate] ${message}" >> "$logdir/$logfile"
}
echoandlogmessage()
{
local message=$1
local _mydate=$(date)
echo "[$_mydate] ${message}" | tee -a ${logdir}/${logfile}
}
logoutput()
{
date=`date`
op="$1"
opoutput="$2"
returncode="$3"
#If error
#if grep -q "EPMAT-" <<< "$2"
if [ $returncode -ne 0 ]
then
failmessage="[${date}] ${operationfailuremessage} ${op}"
logmessage "${failmessage}"
logmessage "${opoutput}"
logmessage "return code: ${returncode}"
else
successmessage="${operationsuccessmessage} ${op}"
logmessage "${successmessage}"
logmessage "${opoutput}"
logmessage "return code: ${returncode}"
fi
}
getLatestReleaseSnapshotDir()
{
local snapshotdirs=$(find ${parentsnapshotdirectory} -type d | sort)
debugmessage "snapshot directories: ${snapshotdirs}"
local latestreleasesnapshotdir=$(echo ${snapshotdirs##*$\n} | rev | cut -d' ' -f1 | rev)
debugmessage "latest release snapshot dir: ${latestreleasesnapshotdir}"
echo "${latestreleasesnapshotdir}"
}
getNextDate()
{
local thisyearmonth=$1
local thisyear=$(echo ${thisyearmonth} | cut -d'.' -f1)
local thismonth=$(echo ${thisyearmonth} | cut -d'.' -f2)
intthismonth=$(bc <<< ${thismonth})
intthisyear=$(bc <<< ${thisyear})
if [ ${intthismonth} -eq 12 ]
then
local intnextmonth=1
local intnextyear=$((intthisyear+1))
else
local intnextmonth=$((intthismonth+1))
local intnextyear=${intthisyear}
fi
nextmonth=$(printf "%02d\n" ${intnextmonth})
nextyear=$(printf "%02d\n" ${intnextyear})
debugmessage "next date: ${nextyear}.${nextmonth}"
echo "${nextyear}.${nextmonth}"
}
init()
{
if [ ! -d "$logdir" ]
then
mkdir $logdir
fi
# removing existing epmautomate debug logs
if ls ./*.log >/dev/null 2>&1
then
rm ./*.log
fi
# remove existing log files
if [ -f "${logdir}/${logfile}" ]
then
rm ${logdir}/${logfile}
fi
}
processCommand()
{
op="$1"
date=`date`
logmessage "$operationmessage $op"
operationoutput=`eval "$epmautomatescript $op"`
logoutput "$op" "$operationoutput" "$?"
}
processSnapshot()
{
local snapshotfile="$1"
local nextdate="$2"
local snapshotname=$(echo "${snapshotfile}" | rev | cut -d'/' -f1 | rev | cut -d'.' -f1)
processCommand "login ${username} ${userpassword} ${serviceurl} ${proxyserverusername} ${proxyserverpassword}"
processCommand "recreate -f"
processCommand "uploadfile ${snapshotfile}"
processCommand "importsnapshot \"${snapshotname}\""
processCommand "runDailyMaintenance skipNext=true -f"
processCommand "downloadfile \"Artifact Snapshot\""
processCommand "deletefile \"${snapshotname}\""
processCommand "logout"
if [ ! -d ${parentsnapshotdirectory}/${nextdate} ]
then
mkdir ${parentsnapshotdirectory}/${nextdate}
fi
runDailyMaintenance -f
logmessage "Renaming \"Artifact Snapshot.zip\" to ${snapshotname}.zip and moving to ${parentsnapshotdirectory}/${nextdate}"
mv "${workingdir}/Artifact Snapshot.zip" "${workingdir}/${snapshotname}.zip" >> "$logdir/$logfile" 2>&1
mv "${workingdir}/${snapshotname}.zip" ${parentsnapshotdirectory}/${nextdate} >> "$logdir/$logfile" 2>&1
}
callSendMail() {
if [[ "${emailtoaddress}" == *"@"* ]]
then
${epmautomatescript} login ${username} ${userpassword} ${serviceurl}
${epmautomatescript} uploadFile "$logdir/$logfile"
${epmautomatescript} sendMail $emailtoaddress "Recreating An Old EPM Cloud Environment results" Body="The results of recreating an old EPM Cloud Environment are attached" Attachments=$logfile
${epmautomatescript} deleteFile "$logfile"
${epmautomatescript} logout
fi
}
#----- main body of processing
date
echoandlogmessage "Starting upgrade snapshots processing"
init
latestreleasesnapshotdir=$(getLatestReleaseSnapshotDir)
latestreleasedate=$(echo "${latestreleasesnapshotdir}" | rev | cut -d'/' -f1 | rev)
debugmessage "latest release date: ${latestreleasedate}"
nextdate=$(getNextDate ${latestreleasedate})
snapshotfiles=$(find ${latestreleasesnapshotdir} -type f -name \*.zip | tr "\n" "|")
if [ ${#snapshotfiles} -eq 0 ]
then
echoandlogmessage "No snapshot files found in directory ${latestreleasesnapshotdir}"
fi
IFS="|"
for snapshotfile in $snapshotfiles
do
echoandlogmessage "Processing snapshotfile: ${snapshotfile}"
processSnapshot ${snapshotfile} ${nextdate}
done
unset IFS
echoandlogmessage "Upgrade snapshots processing completed."
callSendMail