Connector to Oracle Hyperion Financial Management (HFM)

With the Oracle® Hyperion® Financial Management connector, you can use commands in a chain to interact with Oracle Hyperion Financial Management (HFM) version 11.1.2.4.x or 11.2.x. For example, you can create a chain to extract data from Oracle HFM as a file to upload to a Wdata table. 

Note: This connector is built by Workiva and connects to a third-party system. While our Support team can help configure this connector within your workspace, we are unable to troubleshoot or otherwise assist with any issues that originate outside of the Workiva platform.

Prerequisites

To set up the connection, you'll need:

• A server with access to Oracle HFM and installations of:
  • Java Runtime Environment 8 or higher
  • A GroundRunner execution agent

  Note: Install the GroundRunner on an EPM server machine hosting the HFM Application Service.  Workiva cannot provide troubleshooting support when the GroundRunner runs on a different server or network than the Oracle HFM instance.

• Paths to the Oracle Enterprise Performance (EPM) system instance and its HFM home directory.
• The cluster name of the HFM server as it appears in the EPM Shared Services Registry.
• An Oracle HFM integration user, used to authenticate with the Oracle HFM instance.

  Note: The integration user must be a Native Directory user—not a Microsoft® Active Directory® (MSAD) user—with access to data required for Reporting and Extended Analytics. The MSAD user is still needed, but its purpose is to communicate with the GroundRunner.

For assistance when creating and building chains, we also recommend you identify:

• Your Workiva admins
• The Oracle HFM admins
• Your network and infrastructure engineering teams

Set up the connection to Oracle HFM

To set up the connection, an IT admin configures the server, and a workspace owner creates the connection to Oracle HFM.

Step 1. Configure the server

1. In Oracle HFM, create the integration user, and grant them access to Reporting and Extended Analytics.
2. On the server that can access Oracle HFM:
   • Install Java Runtime Environment 8 or higher.

     Note: When installing Java, you may be asked whether to install the Java Development Kit (JDK) or Java Runtime Environment (JRE). Only the JRE is required.

   • Download, install, and activate the GroundRunner execution agent.
   • Allow the host domains for Workiva.

Step 2. Set up the Oracle HFM connector

Note: To make the connector available for use in your organization's chains, an org security administrator first enables it from Configuration.

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under BizApp Connection, select Oracle Hyperion Financial Management and the GroundRunner installed on the server.
3. Under Basic Info, enter a unique name and description to help identify the connection.
4. Under Properties, enter the connection's details:

   Note: Consult your Oracle HFM admin for the correct values.

   Property	Details
   Username	Enter the Oracle HFM integration user's username.
   Password	Enter the Oracle HFM integration user's password.
   EPM home	Enter the path to the HFM home directory for the Oracle EPM system. By default, C:/Oracle/Middleware/EPMSystem11R1.
   EPM instance	Enter the path to the EPM system. By default, C:/Oracle/Middleware/user_projects/epmsystem1.
   HFM cluster	Enter the cluster name for the Oracle HFM server, as it appears in the EPM Shared Services registry.

   Note: All sensitive credentials are automatically encrypted and stored at Advanced Encryption Standard (AES)-256 encryption.

5. Select the workspace environments to use with the connector, and click Save.
6. To test the connection, create and run a chain with the Oracle HFM connector's Extract Members List command, and verify it returns a valid output.

Troubleshooting

Can I use the HFM connector on a load balanced server?

Load balancing is built into HFM and is not controlled by Chains, but you can enter your configuration into the ClusterName field when setting up the connector.

The connection to Oracle HFM fails

Verify the name of the Oracle HFM cluster to connect to, and the Oracle HFM integration user's authentication credentials.

The connector returns a blank output or no response

To ensure the GroundRunner can communicate with the Oracle HFM JAR files, verify the paths to the HFM home directory and EPM instance.

The connector returns an "insufficient permissions" error

Verify the Oracle HFM integration user has both Read and Write access -- not Read only.

Note: The MSAD user--which the GroundRunner depends on--must also have sufficient Read/Write access to any directories that contain files that Chains will interact with.

A command returns an exit code of Success but has no output

If the Clear slice, Copy data, Extract data to database, or Extract data to file command succeeds but has no output, verify its "Expand only" property is not selected. Select "Expand only" to view members with no extraction, such as for testing.

An authentication error occurs when installing on multiple servers

Look for the following line is found in the logs:

 INFO: The file reg.properties could not be found.

If this is found, copy the reg.properties file from Oracle\Middleware\user_projects\config\foundation\11.1.2.0

to

Oracle\Middleware\user_projects\epmsystem1\config\foundation\11.1.2.0.