EPM Automate CLI Reference — The Planning Quest

📋 Prerequisites & Setup

⚠Java 17 Required (EPM 25.06+): EPM Automate requires Java 17. Set JAVA_HOME to your Java 17 JRE. Old Java 8/11 installs cause TLS cipher failures from 25.09 onwards. Download: Settings & Actions → Downloads → EPM Automate

💡Password file (recommended): Never store plain-text passwords in scripts. Generate an encrypted password file: epmautomate encrypt MyPassword myEncryptKey ./passwords/vision.epw — then reference vision.epw in all scripts.

🔐 Authentication 3 commands

login Essential Start an authenticated session with an EPM Cloud environment ▼

# Syntax epmautomate login USERNAME PASSWORD|PASSWORD_FILE URL # Vision Corporation — recommended (encrypted password file) epmautomate login [email protected] ./passwords/vision.epw \ https://vision-prod.planning.ocp.oraclecloud.com/epmcloud # OAuth 2.0 (more secure — EPM 25.06+) epmautomate login [email protected] ./oauth/vision-token.epw \ https://vision-prod.planning.ocp.oraclecloud.com/epmcloud

USERNAMEService Administrator email address. Must have Service Administrator role in OCI Identity.

PASSWORD_FILEPath to .epw encrypted password file. Generated with encrypt command. Preferred over plain-text passwords.

URLFull environment URL including /epmcloud suffix. Found in: Settings & Actions → About.

Note: Creates a session token file in the current directory. All subsequent commands in the same session use this token. Always follow with logout at script end.

logout Essential End the current session. Always include at end of every script. ▼

epmautomate logout

Critical: Always call logout in a finally-equivalent block. Orphaned sessions count against concurrent session limits. In bash: use trap "epmautomate logout" EXIT to guarantee logout even if the script fails mid-run.

encrypt Essential Create an encrypted password file for use in automation scripts ▼

# Syntax epmautomate encrypt PASSWORD ENCRYPTION_KEY PASSWORD_FILE_PATH # Vision Corp — create encrypted password file epmautomate encrypt MySecureP@ss VisionKey2025 ./passwords/vision-prod.epw

Security: Store .epw files in a secure location with restricted read permissions. Never commit to version control. The encryption key is not stored — keep it separately. Regenerate if the key is compromised.

📊 Data Load & Export 6 commands

runDataRule Daily Use Execute a Data Integration data rule to load data into EPM ▼

# Syntax epmautomate runDataRule RULE_NAME START_PERIOD END_PERIOD IMPORT_MODE EXPORT_MODE # Vision Corp — load March actuals (Replace mode) epmautomate runDataRule "Vision_US_Actuals" "Mar" "Mar" REPLACE COMMIT # Load full-year budget data (Accumulate for additive loads) epmautomate runDataRule "Vision_Budget_Load" "Jan" "Dec" REPLACE COMMIT # Validate only — don't commit (check for mapping errors first) epmautomate runDataRule "Vision_US_Actuals" "Mar" "Mar" REPLACE NOCOMMIT

RULE_NAMEExact name of the Data Integration rule as defined in Tools → Data Integration.

START_PERIOD / END_PERIODPeriod names matching DI period mapping (e.g. "Jan", "Feb", "Mar"). Must match the period labels in your DI configuration.

IMPORT_MODEREPLACE clears existing data before loading. MERGE adds to existing. Always use REPLACE for actuals to prevent doubling.

EXPORT_MODECOMMIT writes to Essbase. NOCOMMIT validates mapping only — use to check for errors before a live load.

Vision Corp — Nightly Actuals Pattern

Upload yesterday's GL extract → run data rule → verify count → run calc. See the Nightly Script section for the full chain.

runDataRuleDataset Admin Run a Data Integration rule using a dataset (EPM 25.06+ Data Integration pipeline) ▼

# Syntax — EPM 25.06+ Data Integration epmautomate runDataRuleDataset RULE_NAME DATASET_NAME PERIOD IMPORT_MODE EXPORT_MODE # Vision Corp — dataset-based load epmautomate runDataRuleDataset "Vision_SAP_Load" "VisionDS" "Mar" REPLACE COMMIT

EPM 25.06+: Use with the newer Data Integration pipeline that references Connections and Datasets rather than traditional DM Locations. For legacy Data Management rules, use runDataRule instead.

exportData Admin Export data from an EPM cube to a flat file in the Outbox ▼

# Syntax epmautomate exportData QUERY_NAME FILE_NAME [EXPORT_FORMAT] # Export Vision Budget to CSV epmautomate exportData "Vision_Budget_Export_Q" "Vision_Budget_FY2025.csv" # Then download to local epmautomate downloadFile "Vision_Budget_FY2025.csv" ./exports/

Note: The query must be pre-defined in the application. Output lands in the Outbox — use downloadFile to retrieve it. For large exports, consider splitting by entity or period to avoid query threshold limits.

uploadFile Daily Use Upload a local file to the EPM Cloud Inbox for use in data rules ▼

# Syntax epmautomate uploadFile LOCAL_FILE_PATH [TARGET_FOLDER] # Upload today's GL extract to Inbox epmautomate uploadFile ./extracts/GL_ActualsDaily_20250321.csv inbox # Upload metadata file epmautomate uploadFile ./metadata/Entity_hierarchy.csv inbox

Inbox vs Outbox: Upload to inbox for files that Data Integration will read. Files exported by the system land in outbox — use downloadFile to retrieve them.

downloadFile Daily Use Download a file from the EPM Cloud Outbox to a local path ▼

# Syntax epmautomate downloadFile FILE_NAME [LOCAL_PATH] # Download exported data file epmautomate downloadFile "Vision_Budget_FY2025.csv" ./downloads/ # Download job log from last run epmautomate downloadFile "jobs.log" ./logs/

listFiles Admin List all files currently in the EPM Cloud Inbox and Outbox ▼

epmautomate listFiles # Useful in scripts to verify file upload succeeded before running data rule epmautomate listFiles | grep "GL_ActualsDaily" && echo "File confirmed in Inbox"

⚙ Business Rules & Calculations 4 commands

runBusinessRule Daily Use Execute a single business rule (Groovy or Calc Script) ▼

# Syntax epmautomate runBusinessRule RULE_NAME [PARAM=VALUE ...] # Run master calculation after data load epmautomate runBusinessRule "Master_Calc_Sequence" # Run with runtime parameters (RTP) epmautomate runBusinessRule "Vision_Revenue_Spread" Scenario=Budget Year=FY2025 # Run IT allocation rule epmautomate runBusinessRule "IT_Overhead_Allocation" Scenario=Budget Year=FY2025

RULE_NAMEExact Calculation Manager rule name. Case-sensitive.

PARAM=VALUEOptionalRuntime prompt values as KEY=VALUE pairs. Key must exactly match the RTP name in Calculation Manager (case-sensitive).

RTP case sensitivity: Scenario=Budget works if the RTP is named "Scenario". scenario=Budget will not pass the value. This matches the Groovy executeRule() behaviour.

runBusinessRuleSet Daily Use Execute a Calculation Manager rule set (chained rules in sequence) ▼

# Syntax epmautomate runBusinessRuleSet RULESET_NAME [PARAM=VALUE ...] # Run Vision nightly batch rule chain epmautomate runBusinessRuleSet "Vision_Nightly_Chain" Scenario=Budget Year=FY2025 # Budget cycle master sequence epmautomate runBusinessRuleSet "Budget_Cycle_Master"

Vision Corp Pattern

The nightly batch runs a Rule Set containing: 1) Headcount Cascade → 2) IT Allocation → 3) Validation → in that order. Stop-on-Error is enabled — if Validation fails, the chain halts and Finance is alerted via job log.

refreshCube Admin Refresh the Essbase database outline after metadata changes ▼

# Syntax epmautomate refreshCube [APPLICATION_NAME] # Refresh Vision application after metadata import epmautomate refreshCube Vision

When to run: Always after importing dimension metadata. Without a refresh, new/changed members exist in the Planning repository but not in the Essbase outline — forms and rules referencing them will fail.

clearDataByProfile Admin Clear Essbase data for a specific intersection profile ▼

# Syntax epmautomate clearDataByProfile PROFILE_NAME # Clear Vision Budget Working before re-seeding from Actuals epmautomate clearDataByProfile "Clear_Budget_Working_FY2026"

Caution: This is irreversible without a snapshot restore. Always take a snapshot before clearing significant data intersections. The profile must be pre-defined in the application.

🗂 Metadata Import & Export 4 commands

importMetadata Admin Import dimension metadata from a file into Planning ▼

# Syntax epmautomate importMetadata JOB_NAME FILE_NAME # Import new entity hierarchy file epmautomate uploadFile ./metadata/Entity_FY2026.csv inbox epmautomate importMetadata "Entity_Import_Job" "Entity_FY2026.csv" epmautomate refreshCube Vision # Always refresh after metadata import

Best practice: Chain upload → import → refreshCube in sequence. Each step must complete successfully before the next runs. Add error checking between steps in production scripts.

exportMetadata Admin Export dimension metadata to a file in the Outbox ▼

# Syntax epmautomate exportMetadata JOB_NAME FILE_NAME # Export Entity dimension for EDM comparison epmautomate exportMetadata "Entity_Export_Job" "Entity_Export_$(date +%Y%m%d).csv" epmautomate downloadFile "Entity_Export_$(date +%Y%m%d).csv" ./metadata/exports/

importDimension Admin Import a single dimension from a flat file (simpler than importMetadata for single dims) ▼

# Syntax epmautomate importDimension APPLICATION PLAN_TYPE DIMENSION FILE_NAME [IMPORT_TYPE] # Import Account dimension into Vision OEP_FS plan type epmautomate importDimension Vision OEP_FS Account Account_FY2026.csv Replace

IMPORT_TYPEOptionalReplace replaces all members. Merge adds/updates without removing. Default is Replace.

exportDimension Admin Export a single dimension to a flat file ▼

epmautomate exportDimension APPLICATION PLAN_TYPE DIMENSION FILE_NAME # Export Account dimension for audit epmautomate exportDimension Vision OEP_FS Account Account_Backup_$(date +%Y%m%d).csv

🔧 Substitution Variables & App Settings 3 commands

setSubstitutionVariable Daily Use Update a substitution variable value — all 50+ forms advance automatically ▼

# Syntax epmautomate setSubstitutionVariable APPLICATION|ALL VARIABLE_NAME VALUE # Advance period at month-end — all forms update automatically epmautomate setSubstitutionVariable Vision CurPeriod Apr epmautomate setSubstitutionVariable Vision CurYear FY2025 # Update all applications simultaneously epmautomate setSubstitutionVariable ALL CurPeriod Apr # Update FX rate for monthly close epmautomate setSubstitutionVariable Vision FxRate_EUR 1.085

Vision Corp — Month-End Sequence

At 11pm on the last business day of each month, the nightly batch calls: setSubstitutionVariable CurPeriod [next_month] setSubstitutionVariable PriorYear [updated_if_needed] All 50+ forms and all FRS reports advance their column ranges automatically. Finance arrives to current numbers every morning.

getSubstitutionVariable Admin Read current substitution variable values ▼

# Syntax epmautomate getSubstitutionVariable APPLICATION|ALL [name=VARIABLE_NAME] # Get specific variable epmautomate getSubstitutionVariable Vision name=CurPeriod # Get all variables for Vision application epmautomate getSubstitutionVariable Vision # Use in bash script to read current period CURPERIOD=$(epmautomate getSubstitutionVariable Vision name=CurPeriod | grep "CurPeriod" | awk '{print $2}') echo "Current period: $CURPERIOD"

skipUpdate Admin Skip the next monthly Oracle EPM Cloud update for this environment ▼

# Skip next monthly update (use sparingly — max 2 consecutive skips) epmautomate skipUpdate # Check current skip status epmautomate skipUpdate status

Use case: Skip the monthly update if it lands during budget close week or a critical go-live period. Oracle allows a maximum of 2 consecutive skips. After 2 skips, the update is mandatory.

💾 Snapshots & LCM 4 commands

exportSnapshot Essential Export a full application backup snapshot to the Outbox ▼

# Syntax epmautomate exportSnapshot SNAPSHOT_NAME # Create daily backup snapshot epmautomate exportSnapshot "Vision_Daily_$(date +%Y%m%d)" # Before any major change — always snapshot first epmautomate exportSnapshot "Vision_PreMetadataChange_$(date +%Y%m%d_%H%M)" epmautomate downloadFile "Vision_PreMetadataChange_$(date +%Y%m%d_%H%M).zip" ./backups/

Best practice: Run exportSnapshot + downloadFile nightly. Oracle recommends downloading the maintenance snapshot to a local server every day. A snapshot you cannot retrieve is not a backup.

importSnapshot Admin Restore an environment from a snapshot (full or partial restore) ▼

# Syntax epmautomate importSnapshot SNAPSHOT_NAME # Restore from yesterday's backup epmautomate uploadFile ./backups/Vision_Daily_20250320.zip epmautomate importSnapshot "Vision_Daily_20250320"

Critical: importSnapshot overwrites existing environment configuration. Use only in Test environments for testing restore procedures. Production restores typically require Oracle Support involvement for large environments.

copySnapshotFromInstance Admin Copy a snapshot from one EPM Cloud instance to another (Prod to Test migration) ▼

# Syntax epmautomate copySnapshotFromInstance SOURCE_URL SOURCE_USER SOURCE_PWD_FILE SNAPSHOT_NAME # Copy prod snapshot to test for regression testing epmautomate copySnapshotFromInstance \ https://vision-prod.planning.ocp.oraclecloud.com/epmcloud \ [email protected] ./passwords/vision-prod.epw \ "Vision_Daily_20250321"

Use case: After monthly production update, refresh test with latest prod data. Critical for pre-release testing before production go-live. Note: Essbase version compatibility matters from 25.09 (see What's New 25.09).

listMigrationArtifacts Admin List artifacts available in Migration (LCM) ▼

epmautomate listMigrationArtifacts SNAPSHOT_NAME # List what is inside a snapshot before restoring epmautomate listMigrationArtifacts "Vision_Daily_20250321"

🛡 Security & User Management 4 commands

addUsers Admin Provision users and assign roles from a CSV file ▼

# CSV format: Username,FirstName,LastName,Email,ServiceRole,AppRole # Example users.csv row: # [email protected],John,Smith,[email protected],User,Planner epmautomate uploadFile ./security/new_users.csv epmautomate addUsers "new_users.csv"

Bulk onboarding: Use at the start of each budget cycle to provision seasonal planners or new employees. Remove inactive users promptly — unused accounts are a SOX audit finding.

removeUsers Admin Deprovision users from EPM Cloud ▼

epmautomate removeUsers USERS_FILE # Remove departed employees — run quarterly from HR feed epmautomate uploadFile ./security/departed_users.csv epmautomate removeUsers "departed_users.csv"

exportUserAuditInfo Admin Export user access audit report for SOX/compliance review ▼

# Syntax epmautomate exportUserAuditInfo REPORT_TYPE FILE_NAME # Export quarterly access review for SOX epmautomate exportUserAuditInfo ALL "Vision_Access_Audit_Q1_2025.csv" epmautomate downloadFile "Vision_Access_Audit_Q1_2025.csv" ./audit/

SOX Compliance

Run exportUserAuditInfo quarterly and after any budget cycle. Provides a complete list of who has access to what roles. Hand to internal audit as evidence of access control review.

exportAppAuditData Admin Export data change audit records (who changed what and when) ▼

epmautomate exportAppAuditData START_DATE END_DATE FILE_NAME # Export March data change audit for auditors epmautomate exportAppAuditData "03/01/2025" "03/31/2025" "Vision_DataAudit_Mar2025.csv" epmautomate downloadFile "Vision_DataAudit_Mar2025.csv" ./audit/

Prerequisite: Application audit must be enabled in Application Settings before any data is entered. Enabling audit after data exists does not capture historical changes.

✅ Workflow & Approvals 2 commands

lockPlanningUnit Admin Lock a planning unit after CFO approval — prevents all further edits ▼

# Syntax epmautomate lockPlanningUnit APPLICATION SCENARIO YEAR # Lock all Vision Budget planning units after CFO sign-off epmautomate lockPlanningUnit Vision Budget FY2025 # Lock specific entity (requires entity filter in newer versions) epmautomate lockPlanningUnit Vision Budget FY2025

Vision Corp — Budget Lock Pattern

After CFO approves all 12 entities in the approval workflow, Finance Admin runs lockPlanningUnit. All budget data is frozen. Any subsequent change requires an explicit adminunlock + justification in the audit log. This is the SOX control point.

resetService Admin Switch the environment between Administration and Normal mode ▼

# Switch to Admin mode — blocks non-admin users epmautomate resetService true # Return to Normal mode — users can log in again epmautomate resetService false

Use case: During major metadata changes or a full data reload, switch to Admin mode to prevent users from accessing stale or partially-updated data. Always return to Normal mode immediately after the maintenance window.

🩺 Diagnostics & Reporting 3 commands

runReportingObjectJobset Daily Use Run a report job set (multiple FRS or Reports objects in sequence) ▼

epmautomate runReportingObjectJobset JOBSET_NAME # Run Vision CFO Board Pack nightly epmautomate runReportingObjectJobset "Vision_CFO_Daily_Pack" # Run month-end close pack epmautomate runReportingObjectJobset "Vision_MonthEnd_Pack"

Vision Corp Pattern

The nightly batch ends with runReportingObjectJobset to generate the CFO morning pack. Finance finds PDF reports in their inbox each morning — zero manual steps required.

simulateConcurrentUsage Admin Simulate concurrent users opening/saving forms and running rules — load testing ▼

# Syntax (EPM 25.08+: Save Form runs without specifying cells) epmautomate simulateConcurrentUsage REQUIREMENTS_ZIP [iterations=N] [email=addr] # Run with 10 iterations, email results to admin epmautomate uploadFile ConcurrentUsageFiles.zip inbox epmautomate simulateConcurrentUsage "ConcurrentUsageFiles.zip" iterations=10 [email protected]

EPM 25.08 enhancement: Save Form use case can now run without specifying cells — simulate opening and saving forms to trigger all attached rules. Use before budget cycle opens to verify performance under load (50 concurrent planners).

getDimensionOverview Admin Export a summary of dimension member counts and hierarchy statistics ▼

epmautomate getDimensionOverview APPLICATION FILE_NAME # Get Vision dimension stats epmautomate getDimensionOverview Vision "Vision_DimOverview.csv" epmautomate downloadFile "Vision_DimOverview.csv" ./admin/

🌙 Vision Corp — Complete Nightly Batch Script

Copy this as your starting template. Adapt environment URL, credentials path, and rule names. Designed to run via cron at 11pm on weeknights.

vision-nightly.sh — Production Nightly Batch

#!/bin/bash # ═══════════════════════════════════════════════════════════════ # VISION CORPORATION — Nightly EPM Automate Batch # Runs: 11pm weeknights via cron # Requires: Java 17, epmautomate installed, vision-prod.epw # ═══════════════════════════════════════════════════════════════ EPM="epmautomate" URL="https://vision-prod.planning.ocp.oraclecloud.com/epmcloud" USER="[email protected]" PWD="./passwords/vision-prod.epw" DATE=$(date +%Y%m%d) LOG="./logs/nightly_${DATE}.log" # Trap ensures logout even on failure trap "${EPM} logout; echo 'Session closed' >> ${LOG}" EXIT echo "=== Vision Nightly Batch ${DATE} ===" >> $LOG # ── Step 1: Authenticate ─────────────────────────────────────── $EPM login $USER $PWD $URL >> $LOG 2>&1 if [ $? -ne 0 ]; then echo "FATAL: Login failed" >> $LOG; exit 1 fi # ── Step 2: Upload yesterday GL extract ──────────────────────── $EPM uploadFile ./extracts/GL_Actuals_$DATE.csv inbox >> $LOG 2>&1 # ── Step 3: Load actuals via Data Integration (Replace mode) ─── $EPM runDataRule "Vision_US_Actuals" "Mar" "Mar" REPLACE COMMIT >> $LOG 2>&1 $EPM runDataRule "Vision_EU_Actuals" "Mar" "Mar" REPLACE COMMIT >> $LOG 2>&1 $EPM runDataRule "Vision_APAC_Actuals" "Mar" "Mar" REPLACE COMMIT >> $LOG 2>&1 # ── Step 4: Advance substitution variables ───────────────────── $EPM setSubstitutionVariable Vision CurPeriod Mar >> $LOG 2>&1 $EPM setSubstitutionVariable Vision CurYear FY2025 >> $LOG 2>&1 # ── Step 5: Run master calculation chain ─────────────────────── $EPM runBusinessRuleSet "Vision_Nightly_Chain" \ Scenario=Actual Year=FY2025 >> $LOG 2>&1 if [ $? -ne 0 ]; then echo "ERROR: Calc chain failed — check job console" >> $LOG # Send alert email (optional — use mailx or sendmail) exit 1 fi # ── Step 6: Generate CFO morning report pack ─────────────────── $EPM runReportingObjectJobset "Vision_CFO_Daily_Pack" >> $LOG 2>&1 # ── Step 7: Export snapshot + download backup ────────────────── $EPM exportSnapshot "Vision_Daily_${DATE}" >> $LOG 2>&1 $EPM downloadFile "Vision_Daily_${DATE}.zip" ./backups/ >> $LOG 2>&1 # ── Logout handled by trap ───────────────────────────────────── echo "=== Nightly batch COMPLETE ===" >> $LOG exit 0

💡Schedule with cron: Add to crontab: 0 23 * * 1-5 /opt/scripts/vision-nightly.sh — runs at 11pm Monday through Friday. Add error email notification to catch failures before Finance arrives at 8am.

⚠Deprecated from 26.02: setIPAllowList and getIPAllowList commands will be removed. Migrate to Network Perimeter in OCI Identity before February 2026.

⚙ EPM Automate CLI Reference