Narrative Reporting Snapshot Downloads with EPM Automate

Back in April 2020 I wrote a post about how to download Narrative Reporting (NR) snapshots with the File Transfer Utility.  This utility was needed because at the time EPM Automate did not support NR.  Oracle has recently introduced lots of new functionality in EPM Automate that supports NR, including the ability to download files.  This is exciting because EPM Automate is a much easier tool to use compared to the File Transfer Utility, at least in my humble opinion.

This post will be on using the downloadFile command and automating the daily archiving of the NR snapshot.  Full documentation for EPM Automate can be found at https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/cepma/index.html. 

Simple batch scripts can be created that login to EPM Automate, execute the download, move and rename the snapshot file, and delete old files so as to maintain the most recent downloads.  The script can also include logging of all the activity if desired. 

Here is an example of a batch script that will download and retain the 10 most recent files, and create a log of the results. 

This script is nearly identical to the one I use for archiving Planning snapshots.  The main difference is the file name of the snapshot and the file extension.  This is a critical difference, without the correct file name or extension, the process will fail.

Let’s break out some of the sections and highlight what is happening.

Connection Details & Environment Variables

1. Application URL and login credentials.  User has to be provisioned as a Service Administrator.  Recommended to use encrypted password.
2. The variable for the NR snapshot name has to be “EPRCS_Backup.tar.gz”.  If this was a Planning snapshot, the name would be “Artifact Snapshot”.  Note the extension “.tar.gz”, this has to be included.
3. The script name and variables can be set using batch commands that retrieve the script file name and the directory from which it is executed.  These variables can be hard-coded as well, whichever way is easier for your situation.
4. The variables for the log and file directories are based on the other variables.  These locations need to be created prior to executing the script.  As with the other variables, the values can be hardcoded. Often the file and log directories are on another computer/server, just hardcode the appropriate folder path.

Login

1. Logging into the environment using the variables set at the beginning of the script.  Includes “>> %log%” to record the login to the log.  This is done throughout the script to record the different steps. 
2. Extra command added so if there is an error on the login, the script jumps to the end and terminates.  You will see this line in several places in the script.  I have found it helpful in the past when troubleshooting issues, but it is not necessary to include.

Download the Snapshot

1. The snapshot is downloaded with the command “downloadfile”.  Included is the error check and logging of the different steps.

Logout

1. Logout is done with the command “logout”.  Again, activity is recorded to the log and checked for errors.

Here’s what the log file looks like after these steps. 

Now that the snapshot has been downloaded, the file can be moved to the archive directory and renamed with a timestamp.  The EPM Automate command “downloadfile” downloads the file to the same directory where the batch script is located and executed.  The file is moved to keep it better organized and for maintaining a specified number of backups.  The destination can be on a different computer.

Move and Rename

1. Variables defined at the beginning are used for the source directory and destination directory, a batch command is used to move the file.
2. A batch command is used for the rename.  The rename is partially hardcoded to ensure we maintain the correct file extension.  The NR snapshot has to be appended with “.tar.gz” for it to be used in a restoration of the application.  The rest of the name can be customized.

Once the file is moved into the destination directory, old snapshots can be deleted.  The number of files retained is up to you.  I typically retain 10, you can change the variable “maxSnapshotCount” at the beginning of the script as needed.

Delete Oldest

1. Batch command to count the number of files in the directory.
2. Batch command to delete files if current count exceeds maximum count set by “maxSnapshotCount” variable.  There are multiple ways to do this deletion, but I have found this coding has worked best to ensure the oldest is deleted based on file date and time.  Also, I have had to hard code the directory path instead of using the variable “filesDir” for some clients.

Here’s the rest of the log file.

Once you have a script created and working, you can schedule it to run daily using various scheduling tools.

What I have shown here is not the only way to automate downloading of application snapshots.  Oracle has examples in their documentation and I’ve seen several different ways to write batch scripts from my colleagues.  Some people prefer to use PowerShell instead of batch, one of these days I am going to learn how to do it that way.

As always, happy EPM’ng!