EPM Automate for PBCS

The Definite Starter Guide

Start Automating your Oracle EPM Cloud Processes

EPM Cloud

For more information:

Visit our Website
Integrated,
Integrated, Compliant and Validated Financial Compliant
Data at ANY and
POINT IN Validated Financial Data atFollow
TIME ANY POINT IN TIME
us on LinkedIn
Follow us on Twitter
Table of Contents

Overview ....................................................................................................................................................... 4
About this Guide ....................................................................................................................................... 4
What is EPM Automate? ........................................................................................................................... 4
What will you learn in this Whitepaper? .................................................................................................. 4
Setting Up EPM Automate ............................................................................................................................ 5
Download and Install EPM Automate ....................................................................................................... 5
Configure EPM Automate Environment ....................................................................................................... 7
Gather Information about your Application ............................................................................................. 7
Test Basic Connectivity to your EPM Cloud application ........................................................................... 7
Encrypt the Password ............................................................................................................................... 8
Create a Parameter File ............................................................................................................................ 9
Common Commands for Planning and Budgeting Cloud Service (PBCS/EPBCS) ........................................ 10
Administration ........................................................................................................................................ 10
Download Snapshot ............................................................................................................................ 11
Set Substitution Variable .................................................................................................................... 13
List Substitution Variable .................................................................................................................... 15
Manage Files ........................................................................................................................................... 17
Upload File .......................................................................................................................................... 17
Delete File ........................................................................................................................................... 17
List Files ............................................................................................................................................... 18
Manage Data ........................................................................................................................................... 20
Import Data ......................................................................................................................................... 20
Export Data ......................................................................................................................................... 22
Run Data Management Rule ............................................................................................................... 23
Run Business Rule ............................................................................................................................... 24
Manage Metadata .................................................................................................................................. 25
Export Metadata ................................................................................................................................. 25
Import Metadata................................................................................................................................. 26
Refresh cube ....................................................................................................................................... 27

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME
Overview

If you are an Oracle EPM Cloud customer, you have very likely wondered how to automate your
processes and the most common answer to this question is to use a utility called “EPM Automate”.

About this Guide

Note: please be aware that EPM Automate commands and Oracle EPM Cloud functionality changes
from time to time. Use this reference as a starting point, but make sure to test and read the most
current documentation for additional details.

What is EPM Automate?

EPM Automate is a command line utility for Oracle EPM Cloud applications, like PBCS/EPBCS, FCCS,
ARCS, EDMCS etc. Therefore, it is an easy option to create simple automation scripts. After installing the
utility and configuring a parameter file for the environment, users can write scripts to perform
administration and processing tasks. Not only does automation reduce the amount of manual tasks, but
it also results in repeatable processes and therefore increases confidence in the application.

Here are some common automation tasks, separated by category:

- Administration: managing files and snapshots, refresh cube, switching to admin mode, reset
service
- Business Logic: running Business Rules and Data Management processes
- Data Management: importing/exporting data, metadata and mappings, updating variables
- Security: managing users and groups, creating audit reports

Now that you have an idea what you can automate with Oracle’s EPM Cloud automation utility, it’s time
to see first hand how you can leverage this tool. Not only will this allow you to create scripts that will
perform the manual tasks you would need to take care of yourself, but it will also allow you to focus on
the more important tasks of your job.

What will you learn in this Whitepaper?

The purpose of this whitepaper is to give you a jump-start into using EPM Automate effectively. We are
going to connect to a PBCS application, but it could just as well be FCCS, ARCS, EDMCS etc.

You will learn the ropes of this tool as well as what its limitations are so that you can make informed
decisions on how to use it. The gray boxes contain information that we’ve learned over time so that you
can set everything up based on best practices right away.

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Additionally, you will also learn about an alternate approach using an integration platform called “ICE
Cloud” which allows you to do everything that EPM Automate does, but also offers functionality that
goes way beyond what EPM Automate offers.

Enjoy the read and don’t hesitate to send us any questions or feedback: info@fintechinnovations.com

Setting Up EPM Automate

This chapter shows how to set it up EPM Automate. First you need to download and install the client
utility, then we recommend to configure each environment using a configuration file which simplifies
maintaining the processes:

- Download and Install EPM Automate

- Configure EPM Automate Environment
o Gather Information about your Application
o Create a Parameter file
o Create Encrypted Password file
o Test Login to Oracle EPM Cloud

Does this seem complicated? Do you want to by-pass this setup and build seamless processes in less
time? Scroll to page xxx to learn how to do this easier using ICE Cloud.

Download and Install EPM Automate

Here are the steps to download and install the utility:

1. Log in to your Oracle EPM Cloud application

2. Click on your user name in the top right corner and open the Downloads page

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

3. Download the utility for your operating system: Windows or Linux/Max

4. Save the file (depending on your browser and operating system, it might automatically be saved
to your Downloads folder)
5. The name of the downloaded file is EPM Automate.exe. Right-click on the file, choose Run as
Administrator and follow the instructions. By default, the installer creates a folder called
C:\Oracle\EPM Automate which can be used unless you want to create it in a different folder.

Why would you want to move the EPM Automate client to a different folder?

You should install EPM Automate on a computer and in a location on the file system that
a) you CAN access easily, but
b) any unauthorized users CANNOT access easily.

Please note: accessing the EPM Automate folder can be tricky and make life unnecessarily
complicated, especially when you are not in the office or connected to VPN. <Here> is a
solution to this problem.

6. After downloading and installing the client utility, you will see the following subfolders in your
installation directory (by default: C:\Oracle\EPM Automate):

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

 7. We recommend creating two additional folders
a. A folder called scripts under EPM Automate, to store your custom batch scripts.
b. A folder called admin_only under the scripts folder, to store your parameters and
password files as well as the commonly used Login and Logout scripts

Configure EPM Automate Environment

Please note: in this example we are going to connect to a PBCS application, but it could just as well be
FCCS, ARCS, EDMCS etc.

Gather Information about your Application

You will need the following information in order to connect to your EPM Cloud application:

- EPM Cloud URL (e.g. https://planning-test-a123456.pbcs.us2.oraclecloud.com)

- Domain Id (e.g. a123456)
- Username (e.g. ice-cloud@fintechinnovations.com)
- Password (e.g. iceCloudRocks!)

Test Basic Connectivity to your EPM Cloud application

Please note: we are going to configure the EPM Automate environment using best practices, but for
now let’s keep things simple since this is the first time you are using it. We want to make
sure you can connect without any problems before we parameterize the commands. If
you cannot make the connection using the following steps, then there is no point in
setting up the advanced method anyway.

Here are the steps to confirm basic connectivity:

1. Open a Command Prompt: press the Start key and type cmd
2. Switch to the following directory: cd C:\Oracle\”EPM Automate"\bin
3. Enter the following command to try to log in to your EPM Cloud application

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

 epmautomate.bat login <USERNAME> <PASSWORD> <EPM_CLOUD_URL> <DOMAIN_ID>

4. The login process takes a few seconds and afterwards you should see Login successful as
confirmation.

Here is a screenshot of this. Of course the credentials are blanked out. Please make sure that no one
gets access to your password!

What is happening in the background?

When you login to your Oracle EPM Cloud application, EPM Automate creates a file called .prefs in the
folder from which you execute the LOGIN command. Since we were in folder C:\Oracle\EPM
Automate\bin for testing purposes, the file has been created in this directory. This is not a good place to
run the LOGIN command from, but it will work for now.

Encrypt the Password

Since we are working with mission-critical data in our EPM applications, we need to make sure that we
are securing our access credentials so that no one other than yourself knows the password and can act
on your behalf or access sensitive data without permission.

EPM Automate provides a way to encrypt a password in a password file. It uses Transport Layer Security
(TLS) with SHA-2/SHA-256 Cryptographic Hash Algorithm1 to secure communication with EPM
Automate.

Please note that it is good practice to create a service account which is only used for EPM Automate
processes. Consider creating a dedicated account for this matter.

Here are the steps to encrypt the password:

0. Prerequisite: the user must be a Service Administrator

1
According to Appendix A, reference 1

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

 1. Login to EPM Automate as described in the previous section about Test Basic Connectivity to
your EPM Cloud application.
2. In a command prompt, please enter the following command and replace the values for
password with your actual password, and choose an encryption key (any value should work, for
example, myKey).

epmautomate encrypt <password> <encryptionkey> "C:\Oracle\EPM

Automate\admin_only\test-123456.epw"

Running this command will create a file with the name password.epw in the specified folder
which contains the encrypted password.

3. Review the results. It should say “encrypt completed successfully”:

4. Confirm that the file has been created.

Create a Parameter File

Save yourself a lot of time and hassle

This step is optional, but after setting up EPM Automate we highly recommend to create a
parameter file so that you can manage environment specific information in one place rather than
having to update the information in multiple places. This will save you a lot of time and hassle when
updating user credentials as well as after migrating the files to a different environment (e.g. from
TEST to PROD) because credentials only need to be modified in one single file rather than all over the
place.

Create a file named epm_init.bat and add the following lines (please note: REM indicates that a
comment is following, used to describe the information that is provided):
REM path to EPM Automate batch script
SET EPM_AUTOMATE_PATH="C:\Oracle\EPM Automate\bin\epmautomate.bat"
REM URL of EPM Cloud environment
SET EPM_CLOUD_URL=https://planning-test-
a123456.pbcs.us2.oraclecloud.com
REM Domain Id
SET DOMAIN_ID=a123456
REM EPM Cloud Credentials – Username
SET USERNAME=<user name/email>
REM EPM Cloud Credentials - Password
SET PASSWORD_FILE=”C:\Oracle\EPM Automate\admin_only\test-123456.epw”

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Common Commands for Planning and Budgeting Cloud Service
(PBCS/EPBCS)

On the next few pages you will learn how to set up the following commands:

- Administration:
o Download Snapshot
o Set Substitution Variables
o List Substitution Variables
- Manage Files:
o Upload File
o Download File
o Delete File
o List File
- Manage Data:
o Import Data
o Export Data
o Run Data Management Rule
o Run Business Rule
- Manage Metadata:
o Export Metadata
o Import Metadata
o Refresh cube

Administration

Based on your daily maintenance schedule, PBCS creates a snapshot of your application. This snapshot
will be recreated on a daily basis. EPM Automate allows to download the file or to rename it so it does
not get overwritten. There are also many other tasks including setting and getting substitution variables.

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Download Snapshot

The following command downloads a snapshot from the cloud environment to the local file system.
Please note that snapshots might be 10s or even 100s of gigabytes in size and can take a long time to
download. The file will be downloaded to the folder from which the command was executed.

Command:
epmautomate downloadFile <Name/path of file to download>

Example:

The file will be downloaded to the folder from which this command is called, in this case “C:\Oracle\
EPM Automate\GettingStarted”.

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Downloading Snapshots with ICE Cloud:

- Only requires one step without scripting

- It is easy to define a file name and path to archive the snapshot

- The log information helps to understand quickly where the snapshot has been archived

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Set Substitution Variable

The following command sets a value for a Substitution Variable in PBCS. Please note that it is possible to
define multiple substitution variables in this command.

Command:
epmautomate setSubstVars <CubeName> <Name of SubVar>=<Value to be assigned>

Example:

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Setting Substitution Variables with ICE Cloud:

- Defining a step to set a Substitution Variable, assigning an ICE Cloud variable called “FiscalYear”

- Review Process Logs after data

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

List Substitution Variable

The following command lists all or just one (if a name is provided) Substitution Variables of a PBCS
application, either across all cubes (by specifying “ALL”) or only a specific one (if a cube name is
provided).

Command:
epmautomate getSubstVars <CubeName or “ALL”> [name=<Name of a SubVar>]

Example (for listing one or multiple values):

All the Substitution Variables can be listed – now what? If you want to use one of
those values to automate a process, it looks like you will have to write a script to
parse those values.

Please be aware: automating processes with EPM Automate requires a lot of

scripting if you are trying to build a robust process.

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Getting values of Substitution Variables with ICE Cloud:

- Retrieving the value of a single SubVar with ICE Cloud and assigning it to a Variable called
“ICE_FiscalPeriod” in ICE Cloud. This value can then be used to add to an email, as a value to
filter a dataset as well as many other use cases.

- Retrieving all Substitution Variables from PBCS using ICE Cloud comes out of the box

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Manage Files

In this section we will see how we can manage files with PBCS:

- Upload File
- Download File (this works exactly as described here)
- Delete File
- List Files

Upload File

The following command uploads a file from the machine where EPM Automate has been installed to the
cloud inbox. Please note that large files will take a significantly more time than small files, depending on
your upload speed and the speed at which Oracle EPM Cloud can receive the files.

Command:
epmautomate uploadFile <Name/path of file to upload>

Example:

Please note: it is not possible to upload an empty file. This will result in an error.

Delete File

The following command deletes a file from the PBCS inbox.

Command:
epmautomate deleteFile <Name/path of file to upload>

Example:

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

List Files

The following command lists all file from the machine where EPM Automate has been installed to the
cloud inbox. Please note that large files will take a significantly more time than small files, depending on
your upload speed and the speed at which Oracle EPM Cloud can receive the files.

Command:
epmautomate listFiles

Example:

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Getting files with ICE Cloud:

Retrieving the list of files is easy with ICE Cloud and comes out of the box with every PBCS application. If
you are looking for files with a certain name or a certain pattern, they can easily be identified with a
simple operation.

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Manage Data

In this section we will see how we can manage PBCS data:

- Import Data
- Export Data
- Run Data Management Rule
- Run Business Rule

Import Data

The following command imports a data file from the PBCS inbox into a PBCS cube. This requires the data
file to be in the inbox, matching the exact formatting requirements of the file. Please note that the file
will only load successfully if there are no errors. If there is an error (due to a record that is not formatted
correctly or a missing member, the entire file will be rejected).

Command:
epmautomate importData <Name of Import Data job> [name of file to import]

Example:

In this case there was an error and we need to log in to PBCS > Jobs to find out what the problem was:

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME
Export Data

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Run Data Management Rule

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Run Business Rule

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Manage Metadata

o Export Metadata
o Import Metadata
o Refresh cube

Export Metadata

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Import Metadata

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Refresh cube

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME

Appendix A – References

The following references have been used to create potions of this guide:

1. Working with EPM Automate for Oracle Enterprise Performance Management Cloud:
https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-
common/cepma/GUID-3C3F97F0-0EC6-4279-871C-4736865C0EE3.pdf

Cover Image: Title Photo by Goran Ivos on Unsplash

Integrated, Compliant and Validated Financial Data at ANY POINT IN TIME