Sample Client

Overview

The Sample Client is intended as a guide, to assist you in creating your own custom scripts for calling REST Web services to automate your Profitability and Cost Management tasks. It consists of pre-compiled Java code for calling REST services, and an executable script (one for Windows and one for Linux) that serves as a wrapper for calling the Java code.

The Java code is pre-compiled, and the source code is included in case you need to modify and recompile the code. You can only run the Sample Client on the same server as Profitability and Cost Management.

The following instructions are designed to be used on a Windows server; modify them accordingly for Linux.

Setting Up the Sample Client Environment

To set up the sample client environment:

Open a command window on the same machine on which Oracle Hyperion Profitability and Cost Management is installed
Edit the hpm_ws_client.properties to reflect your local settings:
- Delimiter used to separate String literals in paramters string.delimiter=_
- Delimiter used to separate logical entities in parameters:
  When passing multiple POVs at a time, use # as the delimiter to delimit POVs. For example, 2023_January_Actual#2023_March_Actual to pass two POVs
- SecurityPolicy associated with ProfitabilityService, that needs to be used by the sample client.
  
  Note:
  The sample client is programmed to work with only one value: USERNAME_TOKEN
  hpcm.service.security.policy=USERNAME_TOKEN
- The following two values are needed for security policy USERNAME_TOKEN
  - #HSS user name of the Profitability user. hss.username=admin
  - #Password of the username above. hss.password=password123
- The following two values are needed for RESTFUL Web Service URL:
  - HPCM REST URL to access. Example:
```
http://myServer.mydomain.com:19000
 hpcm.rest.url.host=http://myServer.mydomain.com:19000
```
  - HPCM REST URL version which is to be accessed. Example: version=v1

From a command or shell window, set the following environment variables:

Table A-1 Environment Variables for the Sample Client

Variable Location

JAVA_HOME

Variable	Location
JAVA_HOME	Location where Java Development Kit is available: Windows: `SET JAVA_HOME= C:\Oracle\Middleware\Oracle_Home\oracle_common\jdk` Linux: `JAVA_HOME=/usr/c/Oracle/Middleware/Oracle_Home/oracle_common/jdk`
MIDDLEWARE_HOME	Location where Oracle Middleware home is installed. Windows: `SET MIDDLEWARE_HOME=C:\Oracle\Middleware For Linux: export MIDDLEWARE_HOME=/usr/c/Oracle/Middleware`

Location where Java Development Kit is available:

Windows: SET JAVA_HOME= C:\Oracle\Middleware\Oracle_Home\oracle_common\jdk

Linux: JAVA_HOME=/usr/c/Oracle/Middleware/Oracle_Home/oracle_common/jdk

MIDDLEWARE_HOME

Location where Oracle Middleware home is installed.

Windows:

SET MIDDLEWARE_HOME=C:\Oracle\Middleware For Linux:
                                        export
                                    MIDDLEWARE_HOME=/usr/c/Oracle/Middleware

Note:

In a command window, navigate to %EPM_ORACLE_HOME%\products\Profitability\samples\wsclient and then enter the command hpm_ws_rest_client.bat -help to get a list of available functions.

Use the format and operations specified in the sample client file to build your custom script. See Using the Sample Client File for details.

Using the Sample Client File

The sample client file is intended as a guide to help you build your own custom scripts to access Profitability and Cost Management data through Web Services. The sample client files are available in%EPM_ORACLE_HOME%/products/Profitability/samples/wsclient. These files have been created using Batch Script (Windows) and Shell Script (UNIX/Linux).

To use the sample client script file:

In the command window, go to %EPM_ORACLE_HOME%\products\Profitability\samples\wsclient. See Setting Up the Sample Client Environment.
Enter the following command to get information on a specific operation:
hpm_ws_rest_client.bat - help
Select the operation to be performed and enter the following command:
hpm_ws_rest_client.bat - help OPERATION_NAME
For example, to see the usage details of the getPovs operation, enter the command:
hpm_ws_rest_client.bat - help getPovs

To use the sample client script file to perform an operation, enter the command:

hpm_ws_rest_client.bat OPERATION_NAME PARAMETERS

See for samples in Usage Examples.

Usage Examples

Example 1: List All Applications - To obtain a list of all the available applications, enter the command:

hpm_ws_client.bat getApplications

Example 2: List All POVs - To obtain a list of all POVs for a given application, enter the command:

hpm_ws_rest_client.bat getPovs APPLICATION_NAME

Recompiling the Code

The installation deploys both the compiled binary and the source for the REST sample client:

As a compiled binary file, in wsclient/lib/hpcm-wsclient-sample.jar
As source code, in wsclient/src/oracle/epm/webservices/rest/profitability/client

If the source code needs to be recompiled for any reason, you can recompile using Ant. The build.xml file for Ant is available in the wsclient folder.

To recompile the source code:

Compile the source code with the clean and build targets using a command similar to the following.

ant clean build