Groovy allows you to run EPM Automate commands directly in Oracle Cloud EPM
Why use Server-side EPM Automate?
If you’re an Oracle EPM Cloud admin, you’ve most likely used EPM Automate the command-line utility to interact with the REST APIs provided by the environment.
Avoid Installations
In the past, you had to install EPM Automate on your local machine and execute commands from the command-line. However, with Groovy, you can now run commands directly within Oracle Cloud EPM without any local installation required.
No Physical (or Virtual) Hardware Required
Avoid having to deploy a physical (or virtual) machine to execute EPM Automate commands. Scripts on local machines are fine for development and testing, but deploying the scripts on a live production environment requires separate infrastructure.
No Need to Learn BAT or BASH Scripting
I must confess, I do not write BAT/BASH scripts, and using server-side EPM Automate just removes the need to learn it.
Replace Complex REST API calls and Simplify your Code
You might be wondering why you shouldn’t just use the REST API directly, given that EPM Automate is essentially a wrapper around it. In my experience, using EPM Automate in Groovy scripts requires less code than directly invoking the REST APIs, and using EPM Automate makes it a little less daunting and more user-friendly.
Environments that Support Server-side EPM Automate
You can run EPM Automate through Groovy scripts in the following environments:
- All Planning environments (PBCS, EPBCS, Planning, Planning Modules, Strategic Workforce)
- PCMCS
- FCCS
How to Use EPM Automate in a Groovy Script
To use EPM Automate in a Groovy script, you need to be familiar with a few commands
- getEPMAutomate
Retrieves an instance of EpmAutomate that can then be used to invoke EPM Automate commands - execute
This method of EpmAutomate class is used to execute an EPM Automate command. Returns an instance of EpmAutomateStatus class - getStatus
This method of EPMAutomateStatus class returns the execution status returned by the command. Return value 0 indicates success while a non-zero value means command failure - getOutput
This method of EPMAutomateStatus class returns the string output of the command - getItemsList
This method of EPMAutomateStatus class returns the list output of the command
Now, let’s examine a simple example (although it basically does nothing).
EpmAutomate automate = getEpmAutomate()
EpmAutomateStatus status = automate.execute('encrypt', 'password','encryptionKey','password.epw')
if(status.getStatus() != 0) throwVetoException(status.getOutput())
status = automate.execute('login', 'username', 'password.epw', 'url')
if(status.getStatus() != 0) throwVetoException(status.getOutput())
status = automate.execute('logout')
if(status.getStatus() != 0) throwVetoException(status.getOutput())Using getEpmAutomate() you retrieve an instance of the EpmAutomate class which is then used to execute the required commands.
You can use the ‘encrypt’ command to generate a password file that can be used across the scripts, to avoid hard-coding the password in the script itself.
I would keep a dedicated rule for encrypting the password so that it can generate a new encrypted password file (with the same name) every time the password is changed. All other scripts can run on the assumption that the correct password file is always available.
The ‘password.epw’ file is then used to execute the ‘login’ command.
Limitations of EPM Automate Commands on the Server-side
Commands that aren’t available on Server-side EPM Automate
You can execute all EPM Automate commands except for:
- downloadFile — download the file locally from the cloud
- uploadFile — upload the file from the local storage to the cloud
- upgrade — upgrade the installed EPM Automate to the latest version
Since the execution is on the server-side, there is no file transfer (upload or download). If you are using EPM Automate for backup/archival, then you may not be able to use server-side EPM Automate.
Commands that cannot be Executed in the Same Environment as the Groovy Script
Among the remaining commands, some cannot be executed on the same environment you are running the Groovy script in. Therefore, they should be targeted towards a different environment:
- recreate — clears the entire environment and resets it
- replay — used for automated performance testing
- resetService — restart the environment
- restructureCube — execute a full restructure of a BSO cube
In future posts, I will explore the use cases and where I’ve leveraged server-side EPM Automate for administrative or end-user scripts and processes.
