Installation Guide

EPMWARE ®

EPMWARE, Inc.

Updated: February 2020

Information in this document, including URL and other Internet Web site references, is

subject to change without notice. Unless otherwise noted, the example companies,

organizations, products, domain names, e-mail addresses, logos, people, places, and

events depicted herein are fictitious, and no association with any real company,

organization, product, domain name, e-mail address, logo, person, place, or event is

intended or should be inferred. Complying with all applicable copyright laws is the

responsibility of the user. Without limiting the rights under copyright, no part of this

document may be reproduced, stored in or introduced into a retrieval system, or

transmitted in any form or by any means (electronic, mechanical, photocopying,

recording, or otherwise), or for any purpose, without the express written permission of

EPMware Inc. EPMware, Inc. may have patents, patent applications, trademarks,

copyrights, or other intellectual property rights covering subject matter in this document.

Except as expressly provided in any written license agreement from EPMware, Inc., the

furnishing of this document does not give you any license to these patents, trademarks,

copyrights, or other intellectual property.

© 2020 EPMWARE, Inc. All rights reserved.

EPMWARE is a registered trademark of EPMWARE, Inc. in the United States and/or

other countries.

All other trademarks are property of their respective owners.

Contents

Installation Guide .............................................................................................................. 1

Contents ............................................................................................................................. 3

Introduction ....................................................................................................................... 5

Purpose .............................................................................................................................. 6

Prerequisite Software Installations ................................................................................. 6

Database Installation ........................................................................................................ 6

Prerequisites .................................................................................................................... 6

Create Tablespaces ......................................................................................................... 6

Create New Schema ........................................................................................................ 7

GRANT Tablespace Quota to EW schema ..................................................................... 7

GRANT privileges ............................................................................................................ 7

Create Sleep function ...................................................................................................... 8

Create DB Directories ...................................................................................................... 8

GRANT Folder permission............................................................................................... 8

Install Database Objects................................................................................................... 9

Prerequisites .................................................................................................................... 9

Install EPMWARE Schema.............................................................................................. 9

Install CYGWIN ................................................................................................................ 10

Install Cygwin ............................................................................................................. 10

Install Tomcat Apache .................................................................................................... 11

Configure Apache Settings ............................................................................................ 11

Increase Apache Memory .............................................................................................. 11

Set Environment Variables ............................................................................................ 11

Install the EPMware Application .................................................................................... 12

EPMWARE Application WAR file .................................................................................. 12

Windows System Environment Variable ........................................................................ 13

Register Apache as Windows Service .......................................................................... 14

Set JDBC Properties ....................................................................................................... 14

4

EPMware Application Settings .................................................................................... 14

Global Settings .............................................................................................................. 14

Email Settings ............................................................................................................ 15

Planning Classic - Generate Password file ................................................................... 15

To Generate a Password File .................................................................................... 15

Reference Password File in EPMWARE .................................................................... 16

Install EPMware Agent.................................................................................................... 17

Install the Agent on the Target Server ........................................................................... 17

EPMWARE Agent Configuration ................................................................................... 19

Prerequisites .............................................................................................................. 19

Check Pre-requisites .................................................................................................. 19

Agent Properties ......................................................................................................... 20

REST API Token ........................................................................................................ 23

Test Agent connectivity.................................................................................................. 24

Agent Troubleshooting................................................................................................... 25

Agent Logs ..................................................................................................................... 26

Schedule Agent on Windows Servers ........................................................................... 27

Configuring agent as Scheduled Task ....................................................................... 27

5

Introduction

EPMware is a master data management and workflow tool that manages master data

and enforces your organization’s workflow around the everyday processes that surround

your metadata changes. By configuring shared dimensions in EPMware, users request

metadata once and our workflow engine routes the request to obtain approvals and

deploys the metadata to the participating target systems. This allows standardization and

rationalization of your metadata to evolve as your organization develops its master data

strategy. The EPMware dashboard allows users, managers, and application

administrators to monitor the status of metadata requests in real time. Follow a request

from the initial Create stage through its Review, Approve and Deploy stages. A graphical

representation of each request's status in the workflow allows users to identify any

bottlenecks in the metadata request process and determine if an escalation is required.

Seamless integration to Hyperion EPMA, Classic Hyperion Financial Management

(HFM), Classic Essbase and Classic Planning applications allows EPMware to deploy

metadata without manual intervention or file manipulation from an administrator.

Approved metadata is automatically deployed or scheduled for deployment using our

built-in scheduler.

One-click import of your target system hierarchies allows users to clearly visualize how

metadata will appear in their production environments. A configurable security module

integrates with your current LDAP or Microsoft Active Directory (MSAD). Build, maintain

and scale task driven workflows. Administrators model, build and maintain fully dynamic

and scalable workflows using the Workflow Builder™. By using a combination of stages

and tasks, Workflow Builder™ enables creation of any number of workflows that visually

define your organization’s business process, and then enforces it. The Workflow

Builder™ includes reusable workflow tasks, rule-based validations, exception handling,

email notifications for all workflow stages, custom functions and scripting for limitless

customizations. Centrally manage metadata deployments using the EPMware

deployment module. It manages how and when metadata requests are deployed. Load

metadata on demand or schedule a batch to run during off hours. Deployment metrics for

all your EPM applications are on one page. Monitor in real time as “one time” or batches

are deployed to their respective target applications. Create a recurring calendar for daily,

weekly or monthly metadata deployments. Audit reports log every transaction, sign-off &

deployment. EPMware maintains a complete audit trail of all transactions from request to

deployment. Every transaction can be queried using reports included in the Audit module.

6

Purpose

The purpose of this document is to provide instructions on installation of EPMware on

premise application components.

● Oracle Database

● Prerequisite Software Components

● EPMware Database Objects

● EPMware Application Server

Prerequisite Software Installations

1. Install Oracle Database 11.x or 12.x Standard or Enterprise Edition

2. Install the latest version of Jython (www.jython.org)

3. Ensure Jython’s bin folder is in the system path. For example: d:\jython\bin (On

Windows it should be added as a system environment variable)

5. Ensure Java 1.8.x or above is installed. (www.java.com)

6. Ensure Java is in the system path. (On Windows it should be added to the

system environment variables)

7. Install Tomcat Apache Version 8.0.44 (See Installing Tomcat)

Database Installation

Prerequisites

● Oracle database is installed and is running

● Oracle database access as SYS user

Create Tablespaces Create DATA and INDEX tablespaces for EW database objects (tables, indexes and

stored packages etc. using SYSTEM or SYS user.

The following statements are shown as an example. Please consult Database

Administrator for location, size and naming convention of data files associated with

7

tablespaces.

Execute the following statements as SYS user:

CREATE tablespace EWD DATAFILE

'D:\app\epmadmin\oradata\epm\EWD.dbf' SIZE 1024M AUTOEXTEND ON

NEXT 500K MAXSIZE 2048M;

CREATE tablespace EWX DATAFILE

'D:\app\epmadmin\oradata\epm\EWX.dbf' SIZE 10M AUTOEXTEND ON NEXT

500K MAXSIZE 512M;

Create New Schema Execute following statements as SYS user to grant unlimited disk space quota to EW

tablespaces. Unlimited option can be replaced with other values as needed:

CREATE user ew identified by <password>;

GRANT Tablespace Quota to EW schema Login as SYSTEM User and create new user EW as shown below:

alter user ew quota unlimited on EWD;

alter user ew quota unlimited on EWX;

GRANT privileges Execute these statements as SYS user:

grant connect to ew;

grant create table to ew;

grant create sequence to ew;

grant create view to ew;

grant create procedure to ew;

grant create type to ew;

grant execute on dbms_crypto to EW;

grant create job to ew;

8

Create Sleep function

Create Sleep function and provide EXECUTE grant on that function to EW Schema.

Execute three statements as mentioned below using SYS user:

/*Create function under SYS Schema which is wrapper for sleep function. */ CREATE OR REPLACE PROCEDURE sleep(seconds NUMBER)

AS

BEGIN

DBMS_LOCK.SLEEP(seconds);

END;

/

CREATE OR REPLACE public synonym sleep FOR sleep;

GRANT EXECUTE ON sleep TO <epmware schema>;

Create DB Directories

Execute these statements as SYS user.

CREATE OR REPLACE DIRECTORY <ew_schema_name>_archive_db_dir AS

'D:\ew\db\data\archive';

CREATE OR REPLACE DIRECTORY <ew_schema_name>_stage_db_dir AS

'D:\ew\db\data\stage';

CREATE OR REPLACE DIRECTORY <ew_schema_name>_temp_db_dir AS

'D:\ew\db\data\temp';

GRANT READ,WRITE ON DIRECTORY <ew_schema_name>_archive_db_dir TO EW;

GRANT READ,WRITE ON DIRECTORY <ew_schema_name>_stage_db_dir TO EW;

GRANT READ,WRITE ON DIRECTORY <ew_schema_name>_temp_db_dir TO EW;

GRANT Folder permission Grant Read/Write permission to physical folders for following EPMware DB Directories

created in previous step:

9

1. <ew_schema_name>>_TEMP_DB_DIR

2. <ew_schema_name>>_STAGE_DB_DIR

3. <ew_schema_name>>_ARCHIVE_DB_DIR

For Example: (Change actual physical location as per your environment).

BEGIN

dbms_java.grant_permission ( 'EW', 'SYS:java.io.FilePermission',

'D:\ew\db\data\temp\-', 'read,write,delete' );

dbms_java.grant_permission ( 'EW', 'SYS:java.io.FilePermission',

'D:\ew\db\data\archive\-', 'read,write,delete' );

dbms_java.grant_permission ( 'EW', 'SYS:java.io.FilePermission',

'D:\ew\db\data\stage\-', 'read,write,delete' );

COMMIT;

END;

Install Database Objects

Prerequisites

● Oracle EMPWARE Schema is already created with all necessary grants

● Oracle client is installed on the machine from where Database Objects are being

created. This machine does not necessarily have to be EPMWARE server. It can

be any machine from where Database where EPMWARE schema is installed is

accessible.

● Oracle database connection entry is available in TNSNAMES.ora file. To test the

database connectivity, use SQLPLUS (Oracle Client).

● Jython (Latest version) is already installed and its location is in the PATH. (For

windows add location of jython’s home directory in the path).

Install EPMWARE Schema

1. Copy EW Database ew_db_install zip file to database server (OR on a

server which has Databsae client and can connect to EPMWARE Database).

2. Unzip the file

3. Run ew_install.bat. This script will expect three parameters. EW Schema

name, Password and N/Y flag to drop all objects under the EW schema. Default

value for the third parameter is N. If Y is passed, then all objects from schema

10

“EW” are removed before loading new schema objects. If schema name is

different from EW then modify ew_drop_objects.sql file.

4. Result of the batch file will be as shown below.

5. Check the ew_driver.log log file for any errors.

Install CYGWIN

If the EPMware application is installed on a Windows server, install cygwin if it is not

already installed. In addition to this server, Cygwin will need to be installed on all target

servers which have windows o/s and target application are managed by EPMWARE.

Download cygwin from www.cygwin.com and follow instructions on the cygwin site:

http://cygwin.com/install.html.

Install Cygwin

1. Download Cygwin and save the setup.exe file to your Desktop.

2. Run the setup.exe file.

3. Select the defaults for the following options:

a. Install from Internet

b. Install Root Directory: C:\cygwin

c. Install for All Users

4. Specify a folder for the local package directory that is not the Cygwin root folder,

for example, C:\cygwin\packages.

5. Specify the connection method. For example, if the host is connected to the

Internet through a proxy server, specify the proxy server.

6. Select the mirror site from which to download the software.

11

Install Tomcat Apache

Download Tomcat Apache from http://tomcat.apache.org/download-80.cgi

The latest version supported by EPMWare is 8.0.44

1. Download the zip file (or any other format applicable for the install)

2. Transfer the zip file to the EPMWare application server

3. Unzip the file to target location on the server. For Example: d:\apache-

tomcat-8.0.44

Configure Apache Settings

Perform following steps to configure various Tomcat Apache settings. These settings are

documented in RUNNING.txt file located under home directory where Apache is installed.

Increase Apache Memory By default, Apache allocates 256MB memory with fresh installation. Ideally 2 GB of

memory should be allocated to EPMWARE. Please perform following steps to increase

minimum / maximum memory allocation for Tomcat Apache process upon startup.

• Create a file OR edit file setenv.bat file on Windows server (OR setenv.sh on

Linux O/S) located under Apache home/bin folder.

• Add following line in the file (min memory 512M and Maximum memory is 2 GB)

set "JAVA_OPTS=%JAVA_OPTS% -Xms512m -Xmx2048m-

XX:MaxPermSize=256m -server"

Set Environment Variables

• Set Environment variable for JAVA_HOME or JRE_HOME. Path should point to

home directory where JAVA (JDK or JRE) is installed. These variables are used

to specify location of a Java Runtime Environment or of a Java Development Kit

that is used to start Tomcat. The JRE_HOME variable is used to specify location

of a JRE. The JAVA_HOME variable is used to specify location of a JDK. Using

12

JAVA_HOME provides access to certain additional startup options that are not

allowed when JRE_HOME is used. If both JRE_HOME and JAVA_HOME are

specified, JRE_HOME is used. For windows, system environment variable can

also be used to set these variables. Other option could be to use “setenv” file to

specify environment variables.

Install the EPMware Application

EPMWARE Application WAR file

Copy epmware.war file to <apache>\webapps folder.

13

Windows System Environment Variable

Setup environment variable for JRE_HOME

1. Locate folder where JRE is installed.

2. Go to Control Panel→System→Security\System, select Advanced System

Settings.

3. Select Environment Variables button

4. Create New System Variable for JRE_HOME as shown below.

14

Register Apache as Windows Service

From the Apache home folder, navigate to the bin folder and run service.bat script.

For example, service.bat install EPMWARE

For detailed information on additional parameters for Tomcat Service installation, please

refer Tomcat’s website (https://tomcat.apache.org/tomcat-8.0-doc/windows-service-

howto.html).

Set JDBC Properties

Stop the Apache service and navigate to <APACHE_HOME>\webapps\epmware\WEB-

INF\classes folder. The folder will be created only after placing the epmware.war

file in the folder and starting Apache.

Modify fs_custom.properties file for JDBC properties:

#JDBC

jdbc.driver=oracle.jdbc.driver.OracleDriver

jdbc.url=jdbc:oracle:thin:ew@//localhost:1521/epm

jdbc.user=ew

jdbc.password=ew123

jdbc.maxPoolSize=40

jdbc.minPoolSize=5

jdbc.initialPoolSize=5

jdbc.maxIdleTime=300

jdbc.maxStatements=200

jdbc.preferredTestQuery=select 1

jdbc.idleConnectionTestPeriod=60

After modifying this file, restart the apache server.

EPMware Application Settings

Global Settings This section will guide us to configure Global settings for EPMware applications such as,

email settings, application settings etc.

15

To navigate to Global settings, navigate to Configuration→Misc→Global.

Email Settings

Setting Type Value Comments Required

ADMIN User Email

Address

Email Address for

Admin User

This email address

is used to notify

user for EPMWARE

errors.

Required

Append Fixed value

for Email Subject

(Prefix)

Environment name Such as PROD or

TEST

Optional

Email Domain Name EMAIL Domain name Optional

From Email Address Sender’s Email

Address

Required

Override Email

Address

Override Recipient’s

email address

Specify Email

address where all

emails will be

directed to. Useful

in TEST env.

During testing

Optional

Planning Classic - Generate Password file This section is applicable if you have a Planning Classic application and either Auto

Import or enable direct deployment (for the planning application). Generation of a

password file is required, and its location is specified in the Application Configuration

Properties Tab.

To Generate a Password File

1. Logon to the Planning Application Server

16

2. Navigate to folder

D:\Oracle\Middleware\user_projects\epmsystem1\Planning\Plan

ningAppName

3. Run PasswordEncryption.cmd <passwordFile> (specify the full path for

password file)

For Example:

Start Windows Command Prompt and execute following steps to generate Password file.

• cd d:

• cd D:\Oracle\Middleware\user_projects\epmsystem1\Planning\planningApp

• PasswordEncryption.cmd ew_hp_cl_pwd.txt

• Enter password of App user configured in EPMWARE for the Planning

Application

• Expect following result from the script:

“Password has been encrypted and written to the file ew_hp_cl_pwd.txt

successfully!”

Note: If the file path is not specified the Password File is generated at the location

where this command is run.

Note: Planning User that is configured in EPMWARE to communicate should be

granted “LCM Administrator” role else during application import error: “Failed to

authorize user for LCM migrations” will be thrown.

Note: Ensure Application Properties for Planning Classic application for Password

file EPM Instance Home are accurate.

Reference Password File in EPMWARE

1. Select application from LOV, select PASSWORD_FILE from the grid

2. Right click Edit Properties to change the property value

Note: Specify the filename with the full path in the target application parameter as

shown below.

17

Install EPMware Agent

The Agent is required to be installed on each server where EPMware either imports or

exports metadata directly. These files are placed under the home directory of the

CYGWIN user.

In the example below, the agent files are installed on a Windows server.

CYGWIN user name: Administrator

CYGWIN home directory: C:\cygwin64\home\Administrator

EPMware Agent zip file: ew_agent_files.zip

Install the Agent on the Target Server

1. Logon to the server where agent need to be installed

2. Go to the home directory of the CYGWIN user

3. Unzip Agent zip file ew_agent_files.zip directly under the home directory

18

4. Select home directory of the user to extract zip file. By default, it will have

ew_agent_files folder in it which will need to be removed.

5. After extract the folder should look like the following.

19

EPMWARE Agent Configuration

Prerequisites • Java (JRE or JDK) should be installed or available on the On-Premise Server.

• Java version should be 1.8 OR above.

• Ensure java location is in the system path.

• Ensure zip location is in the system path.

• Ensure firewall port is open to communicate to EPMWARE application. If you are using EPMWARE on cloud then port 443 need to be opened up. If you are using EPMWARE on-premise then whatever port Apache is listening to (such as 8080) need to be opened up.

Check Pre-requisites

• Log on to Cygwin terminal

• Enter java -version on command line. See example below.

20

• Check zip is in path or not by entering “zip -v” (or simply zip) on the command

prompt.

Agent Properties

Modify the agent.properties file located where the agent files are installed as shown

below.

Note: This step needs to be performed on each on-premise Server which will directly

integrate with EPMWARE.

21

File Contents (as an example)

On-Premise version of EPMWARE example

ew.portal.server=epmware1.epmware.com

ew.portal.url=http://epmware_server.com:8080/epmware

ew.portal.token=2e6d4103-5145-4c30-9837-ac6d14797523

agent.interval.millisecond=30000

agent.root.dir=C:\\cygwin64\\home\\Administrator

Cloud version of EPMWARE example

ew.portal.server=epmware1.epmware.com

ew.portal.url=http://client.epmwarecloud.com

ew.portal.token=2e6d4103-5145-4c30-9837-ac6d14797523

agent.interval.millisecond=30000

agent.root.dir=C:\\cygwin64\\home\\Administrator

22

Name Description Comments/Example

ew.portal.server “Server Name” configured in epmware

for the target server

See screen shot below

for example

ew.portal.token Generate Agent Token for the user that

will be used to authenticate to

EPMWARE

See screen shot below

for example

agent.interval.millisecond Polling interval in milliseconds 30 seconds is

recommended value.

agent.root.dir Directory name where agent is

installed.

For Windows it is the

folder where Agent is

installed.

agent.params.quote Used only for enclosing agent

parameter values. This character (only

one character) is used to override

default values of single quote character

for Linux operating system target

servers. For Windows Servers no need

to specify this parameter as default

value is setup automatically.

For Windows Servers,

no need to set this

parameter.

For Linux servers

specify “Double quote”

character.

23

Server Name

REST API Token EPMWARE Agents on client’s on-premise servers uses REST APIs to perform tasks

such as Application Import, Deployment etc. EPMWARE agent uses a token (36

character long alpha-numeric value) to login to EPMWARE application using REST

protocol (Representational State Transfer). You can use any user and generate REST

token for it and use this token during Agent Installation on the client’s on-premise servers.

Refer to EPMWARE Agent Installation guide for complete details for EPMWARE Agent

configurations. To generate token, select the user record and using right click mouse

button select “Generate Token” menu item.

24

Test Agent connectivity

From the Cygwin command agent can be executed to check if agents can communicate

with the EPMWARE application or not. Perform following steps to test the Agent

connectivity. Note: You can test the Agent Connection from the EPMWARE application

also from the Infrastructure -> Servers page. Right click the server you want to test the

connection and click on the “Test Connection” button). If connection is alive then success

message will be returned in couple of minutes

1. Start cygwin terminal (ensure you have logged onto the Windows server as same

user under which EPMWARE agents are installed).

2. Execute service command “./ew_target_service.sh” as shown below.

3. If the connection is successful it will start polling. See second image below.

25

Agent Troubleshooting

If you stop the Scheduled task, then java process related to the agent does not get

removed automatically. You must remove the java task before re-starting the agent if the

task is running. You can do that by either using Windows Task Manager and check java

process which is related to the agent (See process details. It will show you the path) and

terminate it. Alternatively, you can check java process at Cygwin terminal too as shown

below.

26

Agent Logs

Agents will produce two log files under “logs” directory. “agent.log” file will show all agent

commands received from the EPMWARE application to be executed locally on the server

and the is the polling file which will show a line every interval set in the agent.properties

file.

Example of contents from agent.log

27

Example of contents from agent-poll.log

Schedule Agent on Windows Servers

EPMWARE agents need to be continuously running on the Windows server and hence it

can be scheduled to run as a Windows scheduled task.

Configuring agent as Scheduled Task

Use the following steps to configure the EPMWARE agent to run as a Scheduled Task on

the Target Server. This step will allow the Agent to start automatically upon server restart.

Perform this task only if Agent is not installed as Windows Service already.

• Logon to the Windows server with Administrator privileges.

• Open Task Scheduler as shown below.

28

• Click on the ‘Create Task” under Actions menu on the right side.

• Create new Task called EPMWARE TARGET AGENT SERVICE

29

• Click on Triggers Tab. Click on New Button. This tab allows when to run the scheduled Task. We will select upon Server Restart.

30

• Click on the “Actions” tab and enter the values shown below.

Change the path of Cygwin if it is different from what is shown in the screenshot

below.

Field Value Comments

Action Start a Program

Script C:\cygwin64\bin\bash.exe Change cygwin path if needed

Arguments -l -c "./ew_target_service.sh"

Start in Path C:\cygwin64\bin Change cygwin path if needed

• Enter the username and password when prompted for that same user under which Cygwin is installed and used for Target Agent.

31

• Check new Scheduled Task as shown below.

• Double Click on the scheduled task “EPMWARE TARGET AGENT SERVICE”.

Click on Run under Actions Menu to start the Scheduled Task. When Server

reboots this process will automatically start.

32

• Verify the Service is running by checking the Agent Log file as shown below.

o Open the agent-poll.log file and see contents populating every 5

seconds (or frequency set in agent configuration file)

o Open the agent.log file and check for errors if there are any.

• To End the process (in case you modify the agent.properties) use the Task

Scheduler to End the process and Start again.