Leveraging REST APIs in EPM Applications

How to use REST APIs in EPM Applications using Groovy scripts

---

Among the many features and capabilities of Oracle EPM, Groovy Rules and REST API are essential components for extending the platform’s functionalities, automating complex business logic, create highly customized and efficient rule-based calculations within your Oracle EPM applications.

Let’s dive in and discover the possibilities that lie at the intersection of Groovy, REST API, and Oracle EPM Planning.

---

Why REST API when you have server-side EPM Automate

Using server-side EPM Automate commands is the simplest approach to accessing/using the REST API of the EPM applications. However, EPM Automate is limited to the local or other EPM environments only.

With REST API, we can:

• use third-party services for data or validations

• use capabilities not yet supported in EPM Automate but offered by the REST API of the EPM application

---

Uses cases

Some example use cases where the ability to connect using REST API’s can be used to automate admin tasks or business processes

• Import/Export

• Backup/Recovery

• Data Integration

• External Solutions

• Third-party Connectors

---

Dissect an example

We’ll use the example code from the documentation.

HttpResponse<String> jsonResponse = operation.application.getConnection("Job Definitions").get().asString()

// Check if the HTTP status code is successful
if(!(200..299).contains(jsonResponse.status))
  throwVetoException("Error occured: " + jsonResponse.statusText)

// Check if content type of the response is json
if(!(jsonResponse.headers?.getFirst("Content-Type") ==~ /application\/json.&#x2a;&#x2f;))
  throwVetoException("Error occured: Unexpected content type in response: ${jsonResponse.headers?.getFirst('Content-Type')}")

def object = new JsonSlurper().parseText(jsonResponse.body) as Map
println "Number of jobs returned: ${((List)object.items).size()}"

getConnection — Returns the connection with the specified name.
The connection is retrieved from the defined list of connections in the EPM application. Creating a connection is discussed later in the post.

An alternate approach to creating a connection (when the connection is not defined in the EPM application) is to create an on-demand connection object.

Connection connection = connection("http://server:port/HyperionPlanning/rest/v3/applications/Vision", "user", "password")

The connection object is used to create an HttpRequest like GET requests or POST requests.

HttpResponse<String> is where we receive the response from the REST API call, and we can use this to get the status of the job (SUCCESS, FAILED, etc.) and also to get the response body that contains the information we have requested.

---

Create Connections in EPM

Create a connection in EPM using the Connections link in the navigation menu to create ready-to-use connections.

Connection Type

Connection Details

Advanced options to provide headers and parameters that always need to be included

The optional advanced options enable you to specify query or header parameters when defining an external connection.

Note: The ability to define query parameters for an external connection is only available for use with those business processes that allow Groovy Rules to be created.

Header sets a default header that will be sent on every request made for this connection.

Parameter sets a default query parameter that will be sent on every request made for this connection.

Connection example

---

HttpRequest

create an HttpRequest object using getConnection

• GET

• POST

• DELETE

• PUT

Giving parameters (header and body)

def params = new JSONObject()
     .put("Entity",rtps.Entity.toString())
     .put("Scenario","Actual")
     .put("Year","FY15")
     .put("Period","Jan")

def body = new JSONObject()
     .put("jobType","Rules")
     .put("jobName","Consolidate")
     .put("parameters",params)
     .toString()



String payload = json([
          "jobType":"DATARULE",
          "jobName":"DLR_DATA_EXPORT_To_File",
          "startPeriod":"Jan" + '-' + yearnum,
          "endPeriod":"Dec" + '-' + yearnum,
          "importMode":"REPLACE",
          "exportMode":"STORE_DATA",
          "fileName":"Export_FilName"+j+".dat" 
        ]);

The above example shows how you can create the objects to pass to the HttpRequest method.

---

HttpResponse

HttpResponse<String> to get the response from the HttpRequest GET or POST methods.

With the HttpResponse object

• you can retrieve the status of the request; and

• the body of the response which is in an XML format

---

With this primer you should be able to

• create a connection in the EPM application or create an on-demand connection in your Groovy script

• use the connection object to initiate an HttpRequest as a GET, POST, etc.

• Receive the response from the API in the HttpResponse object through which you can evaluate the status of your request and the response contents