Configuring the EPM Integration Agent Startup Parameters
Startup parameters for your Oracle Enterprise Performance Management Cloud URL and EPM Cloud domain for EPM Integration Agent, are defined in the agentparams.ini
file.
Note:
Before defining the EPM Integration Agent startup parameters, run the createAppFolder.bat
, which creates an INI file that contains the populated EPM_AGENT_HOME
and EPM_APP_DATA_HOME
parameters. For more information, see Creating Application Folders.
To encrypt the password used by the EPM Cloud user, you must run ecryptpassword.bat
. For more information, see Encrypting the EPM Cloud User Password.
To configure the startup parameters used by the EPM Integration Agent:
-
Go to the
C:\EPMAgentData\config
directory. -
Double click the
agentparams.ini
file to open it using a text editor such as Notepad.agentparams.ini
file opens in a text file: -
EPM_AGENT_HOME
is the name of the home directory of the agent. This folder contains the bin and lib folders.When you run
createappfolder.bat
, the script creates the populatedEPM_AGENT_HOME
parameter automatically.If you change the name of the folder, the agent runs from the new location and files are created in the new
EPM_APP_DATA_HOME
folder. -
EPM_APP_DATA_HOME
is the name of the Application data folder, which contain the config, log, and script folders. The config folder also contains an empty certificate folder, which is not used at this time.When you run the
createappfolder.bat
the script creates an INI file that contains the populatedEPM_APP_DATA_HOME
parameter. -
In AGENT_NAME, specify a unique name for the EPM Integration Agent.
Only characters and numbers can be used in name. The
AGENT_NAME
cannot contain any symbols or spaces. -
In CLUSTER, specify the name of the cluster to which the agent belongs.
Only alphanumeric characters can be used in the name. Do not use special characters such as sign (@) or ampersand (&). The name cannot be modified once the cluster has been created.
The default cluster name is EPMCLUSTER.
Note:
The name of the cluster must already be defined in Data Integration before it can be referenced here. For more information, see Adding a Cluster.
This parameter is required.
-
In PORT, specify the port number where the EPM Integration Agent runs.
This parameter is required.
-
In CLOUD_URL, specify the EPM Cloud URL used to authenticate and start the agent.
This is the URL of the EPM instance associated with the agent, for example:
https://example-pbcs.us1.oraclecloud.com
Note:
Be sure not to include "epmcloud" or "HyperionPlanning" at the end of the Cloud_URL.This parameter is required.
-
In CLOUD_DOMAIN, specify the unique name for the EPM Cloud URL.
An identity domain controls the accounts of users who need access to service instances. It also controls the features that authorized users can access. A service instance belongs to an identity domain.
Administrators can update the domain name that is presented to the user, but Data Management requires the original domain name that was provided when the customer signed up for the service. Alias domain names cannot be used when setting up EPM Cloud connections from Data Management.
Note:
The CLOUD_DOMAIN parameter is required except for any of the Gen 2 data centers. When using the EPM Integration Agent with Gen 2 data centers, you can resolve any errors by removing the domain in theCLOUD_DOMAIN
field. -
In CLOUD_USER_NAME, specify the administrator user name present in the EPM Cloud environment.
The user name must be a native user and not an SSO user name.
This parameter is required.
-
In CLOUD_PASSWORD, specify the encrypted password string for the administrator user.
You can encrypt the password for the EPM Cloud user and get the encrypted password string by running the
encryptpassword.bat
(for Windows) orecryptpassword.sh
(for Linux). For more information, see Encrypting the EPM Cloud User Password.This parameter is required.
-
In LOG_LEVEL, specify the local EPM Integration Agent log level.
The valid log levels include the following:
- ALL—Shows the most detail level and prints all log statements.
- INFO—Prints selected logs which are important.
- ERROR—Performs minimal logging, only fatal errors are printed.
All logs are written to a file within the
APPDATA_HOME\logs
folder.This parameter is optional. All is the default log level.
-
In POLL_INTERVAL, specify the time interval to wait and poll in asynchronous mode.
The time interval is specified in seconds. The default time interval is 120 seconds.
-
In REGISTER_WITH_IP, specify N to register the agent with the host name. Specify Y to register the agent with the IP address.
This parameter is optional.
-
In EXECUTION_POOL_SIZE, specify how many jobs can be run in parallel.
The default execution pool size is 2.
This parameter is optional.
-
In JYTHON_HOME, specify the top-level directory where Jython is installed.
This is required only if you are using Jython as a scripting language.
-
In GROOVY_HOME, specify the top-level directory where Groovy is installed.
This is required only if you are using Groovy as a scripting language.
-
In CUSTOM_MEM_ARGS, specify the variable to override the standard memory arguments passed to Java with a custom memory argument.
For example, in the parameter
CUSTOM_MEM_ARGS=-Xms128m -Xmx4096m
, 128 MB is the minimum initial memory size and 4096 MB is the maximum memory size.This parameter is optional.
-
In CUSTOM_JAVA_OPTIONS, specify any additional Java runtime parameters.
The CUSTOM_JAVA_OPTIONS setting can also be configured to have the EPM Integration Agent use a proxy authentication method.
The system supports the following authentication methods:
- simple
- basic
- digest
- NTLM
If you use a proxy authentication method, specify the proxy host name, proxy port, proxy user name, and encrypted password in this field based on the proxy authentication method.
If the proxy uses basic authentication, then set CUSTOM_JAVA_OPTIONS to:
-Djdk.http.auth.tunneling.disabledSchemes=""
Note:
The Basic authentication scheme has been deactivated by default in Oracle Java Runtime when you add Basic to the jdk.http.auth.tunneling.disabledSchemes networking property. As a result, proxies requiring Basic authentication when setting up a tunnel for HTTPS no longer succeed by default. If required, this authentication scheme can be reactivated by removing it from the jdk.http.auth.tunneling.disabledSchemes networking property.
Simple Proxy Authentication Method:
To enable simple proxy authentication, set NTLM_PROXY_AUTH field above to N and include the following parameters in CUSTOM_JAVA_OPTIONS:
For HTTP, specify:
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=80
For HTTPS, specify:
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=443
Basic or Digest Proxy Authentication Method:
To enable basic or digest proxy authentication, set NTLM_PROXY_AUTH field above to N and include the following parameters in CUSTOM_JAVA_OPTIONS:
-DproxyHost=proxy.example.com -DproxyPort=8080 -DproxyUser=username -DproxyPassword=encryptedpassword
NTLM Proxy Authentication Method:
To enable NTML proxy authentication, set NTLM_PROXY_AUTH to Y and include the following in the parameters in CUSTOM_JAVA_OPTIONS:
-DproxyHost=proxy.example.com -DproxyPort=8080 -DproxyUser=username -DproxyPassword=encryptedpassword -DproxyDomain=domain
-
In CUSTOM_INTERFACE_CLASS_NAME, specify the fully qualified class name of the class in
custom.jar
that implements theEpmAgentInterface
.For example, specify:
com.mycompany.agent.implementation.MyImplementation
.This parameter is optional.
-
In CUSTOM_CLASS_PATH, specify the full path and name of the jar (for example,
C:\AgentDeployment\agenthome\myJarFolder\custom.jar
This parameter is optional.
If you use a Microsoft Java Database Connectivity (JDBC) driver connect to the SQL Server in the EPM Integration Agent, see Configuring the Microsoft JDBC Driver for SQL Server in the EPM Integration Agent.
-
In NTLM_PROXY_AUTH, specify Y to use an NTLM proxy authentication method.
If you use NTLM proxy authentication, you must additionally specify proxy parameters in CUSTOM_JAVA_OPTIONS.
Specify N to use basic or digest proxy authentication, or if you are not using proxy authentication.
Note:
Set JYTHON_HOME or GROOVY_HOME if you want to use Jython or Groovy for scripting.
Set CUSTOM_JAVA_OPTIONS, CUSTOM_INTERFACE_CLASS if you want to use custom Java for your extensions.
-
In AMW_IDLE_TIME, specify the idle time value for agents running in asynchronous mode during the Automated Maintenance Window (AMW) downtime or an unscheduled maintenance.
The AMW_IDLE_TIME parameter value is set in minutes and the default setting is 15 minutes. Customers can define a longer idle time but should not specify an idle time value less than 15 minutes. The AMW downtime is a contiguous time interval during which automated maintenance tasks are run for a business process.
-
In Client_ID, enter the client ID generated when the Identity Domain Administrator configures the mobile application for OAuth. It is visible on the Configuration tab of the application, under General Information. For more information, see Enabling the OAUTH Option in the EPM Integration Agent.
The Client ID is generated when the Identity Domain Administrator configures the mobile application for OAuth. It is visible on the Configuration tab of the application, under General Information.
-
In ENABLE_AUTO_COMMIT, specify the auto-commit setting.
The ENABLE_AUTO_COMMIT parameters determines whether every database operation is a transaction that is committed when performed. This setting addresses errors that may occur during agent processing in some versions of the JDBC Driver (for example, IBM DB2), which perform the auto-commit by default.
To enable auto-commit, specify Y.
To disable auto-commit, specify N.
When using a JDBC driver that does not support auto-commit behavior, specify I to ignore the auto-commit setting.
The default setting is N
-
In RETRY_INTERVAL, specify the retry logic period after a specified number of seconds.
The default is 10 (seconds).
-
In FILE_UPLOAD_SIZE, specify the size of the file upload in iteration by a selected megabyte (MB) value.
By default the file upload size is 50 (MB).
-
Save any changes to the
agentparamas.ini
file.When you have defined the startup parameters, you can run the EPM Integration Agent in diagnostic mode, which provides a way for you to identify any issue with the EPM Integration Agent startup parameters or network connectivity when the agent can't be started. For more information, see Running the EPM Integration Agent in Diagnostic Mode.