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:

1. Go to the C:\EPMAgentData\config directory.

2. Double click the agentparams.ini file to open it using a text editor such as Notepad.

   agentparams.ini file opens in a text file:

   

3. 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 populated EPM_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.

4. 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 populated EPM_APP_DATA_HOME parameter.

5. 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.

6. 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.

7. In PORT, specify the port number where the EPM Integration Agent runs.

   This parameter is required.

8. 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.

9. 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 the CLOUD_DOMAIN field.

10. 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.

11. 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) or ecryptpassword.sh (for Linux). For more information, see Encrypting the EPM Cloud User Password.

    This parameter is required.

12. 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.

13. 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.

14. 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.

15. In EXECUTION_POOL_SIZE, specify how many jobs can be run in parallel.

    The default execution pool size is 2.

    This parameter is optional.

16. 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.

17. 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.

18. 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.

19. 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

20. In CUSTOM_INTERFACE_CLASS_NAME, specify the fully qualified class name of the class in custom.jar that implements the EpmAgentInterface.

    For example, specify: com.mycompany.agent.implementation.MyImplementation.

    This parameter is optional.

21. 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.

22. 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.

23. 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.

24. 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.

25. 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

26. In RETRY_INTERVAL, specify the retry logic period after a specified number of seconds.

    The default is 10 (seconds).

27. 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).

28. 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.