EPM Tech Tips · EPM Automate · 10
The scheduler says the nightly job finished, nobody gets an alert, and in the morning a forecaster finds half of last night's actuals missing. The cause is almost always in the script. Common gaps are a failed command nobody checked, a stale file, the wrong period, or a job that ended with warnings. This guide checks them in a fixed order.
Before you start
Reproduce the run by hand. Open a command window on the server that runs the job, with the same service account, and run the script. Note the last thing it prints and the exit code it returns (echo %ERRORLEVEL% on Windows, echo $? on Linux).
Pick your route. If Data Integration shows the job as failed but the scheduler showed success, start with step 1. If the job shows success and the numbers are still short, go through steps 2 to 6 in order.
Step 1 · Does every command stop the script when it fails?
What happens. Each EPM Automate command returns an exit code. Zero means it ran; a nonzero code (1, 6, 7, 9, 11 or 13) means it did not, and the message tells you why. A batch file does not stop on its own. If you skip the check after one command, the script carries on, ends normally and hands the scheduler a clean exit.
How to check.
Confirm that every epmautomate line in a Windows batch file is called with call. Without it, control does not return to your script after the first command.
Confirm that each command is followed by an exit code check before the next one runs.
Confirm that the script's last line returns the failing code to the scheduler, not a hard-coded zero.
Fix. Use the pattern from Oracle's own sample scripts:
call epmautomate login %user% %pwdfile% %url%
IF %ERRORLEVEL% NEQ 0 goto :ERROR
call epmautomate uploadFile "%srcfile%" inbox/GL
IF %ERRORLEVEL% NEQ 0 goto :ERROR
call epmautomate runIntegration "%job%" importMode=Replace exportMode=Merge periodName="{%period%}"
IF %ERRORLEVEL% NEQ 0 goto :ERROR
call epmautomate runBusinessRule "%rule%"
IF %ERRORLEVEL% NEQ 0 goto :ERROR
call epmautomate logout
exit /b 0
:ERROR
set rc=%ERRORLEVEL%
call epmautomate sendMail "%ops%" "Nightly load FAILED" Body="Exit code %rc%"
call epmautomate logout
exit /b %rc%
In bash, the same idea is epmautomate.sh <command> || fail "<step>" after each line. Log in with an encrypted password file created once with epmautomate encrypt, so no password sits in clear text in the script. Two failures recur in nightly jobs: exit code 11 when the run overlaps the environment's daily maintenance, so schedule around it, and exit code 9 when the service account's password changed and the encrypted password file is stale.
Step 2 · Did today's file reach the inbox?
What happens. uploadFile does not overwrite. If a file with the same name is already in the upload location, the command returns an error and the old file stays. With no check after the upload, the integration runs on yesterday's file and reports success.
How to check.
Run epmautomate listFiles and look for the source file name in the inbox folder your integration reads.
Compare the file size or date on the server with what the source system produced tonight.
Check the source file before you upload it. An empty or truncated extract is a source problem, not an EPM problem.
Fix. Delete the previous copy only if it exists. An unconditional deleteFile fails on the first run or after a cleanup job, and the pattern in step 1 would then stop the load for a harmless reason:
for /f %%i in ('call epmautomate listfiles') do if "%%i"=="inbox/GL/<file>" (call epmautomate deleteFile %%i)
Then upload, and check the exit code of the upload. Stop the script before the upload if the local file is empty or smaller than a minimum you set. Do not count on EPM Automate to reject an empty data file.
Step 3 · Is the integration loading the period you think?
What happens. runIntegration (which replaces the deprecated runDataRule) loads the periods you pass in periodName, and nothing else. A hard-coded period, or a substitution variable nobody rolled forward, loads the right file into the wrong month. Import and export modes matter too: Replace clears the POV before loading, Merge keeps what is there.
How to check.
Print the full runIntegration line to the log before it runs, including periodName.
If you use substitution variables, such as periodName="{&CurMonth#&CurYr}", check their current values in the application and confirm that the period mapping has the Year and Month target values that format needs.
Confirm the parameter names and values are typed exactly as documented. They are case-sensitive.
Fix. Derive the period from one controlled place, either a substitution variable your close calendar owns or a value the script calculates and logs. Pick Replace or Merge on purpose and write down why. Warning: with Replace, a wrong period clears data that was correct in that month, so confirm the period before the first run.
Step 4 · Did the job end with warnings?
What happens. An integration can complete while some records never reach the cube. Unmapped members stop at validation, and invalid intersections are rejected by Essbase on export. Process Details may show a warning status. Oracle documents no separate exit code for a warning, so treat a zero exit code as unproven and check the process status and logs.
How to check.
Go to Data Integration, open Actions › Process Details, and select the process ID for last night's run.
Look at the status of each step and open the log.
For export rejections, open the Output file for that process ID from Process Details, or find it with listFiles.
Fix. Find the run's log with epmautomate listFiles (newest file under outbox/logs for your application), download it with epmautomate downloadFile, and scan it for rejected or error lines before you call the run a success.
Step 5 · Do the totals tie after the load?
What happens. An exit code of zero and a clean log tell you the job ran. They do not tell you the data is complete. Only a control total does.
How to check.
Take a record count and a total amount from the source extract before upload.
After the load and the business rule, pull the same total from the target, for example with a small predefined export data job run by epmautomate exportData and downloaded with downloadFile, or with a Data Integration check rule run with exportMode=Check.
Compare the two in the script.
Fix. Treat a difference above your tolerance as a failure: set a nonzero exit code and send the alert.
Step 6 · Does someone hear about it?
Use epmautomate sendMail to email the result with the log attached, for example Attachments=outbox/logs/<logfile>.log, using the file name you found in step 4. Attachments are limited to 10 MB, and mail only reaches domains on the environment's email allowlist if one is set. sendMail needs an open session, so a failed login needs a local alert from the scheduler or the server. End every path with epmautomate logout.
Quick checklist
Exit code checked after every command, and returned to the scheduler · the script
Old file deleted if present, today's file uploaded and not empty · listFiles, deleteFile, uploadFile
Right period and import/export modes · runIntegration line and substitution variables
No warnings or rejections · Process Details, outbox/logs and the Output file
Control totals tie · source extract vs target
Alert sent, session closed · sendMail, logout
Pedro San Martín · Founder & Principal, Asher & Company
