One of the most important things that Oracle has come up with recently, is extending the capabilities of EPM products, using various REST APIs (Representational State Transfer). For instance, PBCS has a REST API that can be used to run business rules, or load data using these API calls. So does BICS.
Recently, Oracle also came out with the REST API for HPCM. An associate of mine, wanted to see if it was possible to use these APIs for automating routine HPCM tasks. My use case in this example is to use the REST API, to do something extremely simple, get a list of available applications from HPCM.
REST, allows us to use a few different methods. Those that apply primarily to us, as EPM developers, are GET, POST, PUT and DELETE. There’s nothing fancy about those methods. GET allows you to retrieve some data from an application. POST allows you to create an action (like executing a business rule). PUT allows you to make updates and DELETE, does what you think it would do. Now I am not a web developer, but the beauty of REST, is that you don’t need to be one. You can still do a variety of actions with this tool.
According to the screenshot above, we need a few things to make the REST call work:
- The base URI for Workspace, which is usually, something along the lines of: http://servername.com:19000
- We need to add on the name of the tool we are using, in this case, “profitability”.
- Specify the rest key word and the version of the API. In this case it’s “v1”, but be on the lookout for updated versions of the API (PBCS is on version 3 ATM).
- Finally, the “applications” key word.
If we add all of those together, we get a URI which looks like:
http://servername.com:19000/profitability/rest/v1/applications
If we just use that URI above, that’s not going to work. We need to provide a couple more details:
- Authorization: whether it’s HPCM or PBCS, we need to provide authorization credentials that can be used as the authorization layer. EPM products require “basic” authorization.
- Content Type: responses and parameters in Oracle’s REST world are encoded in JSON Think of this as a collection of arrays that can be passed seamlessly to web URLs.
There are different ways in which you can invoke these APIs. You could use Java, Python, cURL or Groovy. For the sake of this example, I’ll use Groovy, because, well, the name. Groovy can be downloaded from here and provides a console which can be used to run your code.
Let’s try something super simple; let’s see what happens if we just try to access the basic Workspace URL through Groovy.
|
1 2 3 4 5 |
address = "http://unlk.cube.com:19000/" // Basic URL urlInfo = address.toURL() // Convert to a URL connection = urlInfo.openConnection() // Open the connection println "Response Code/Message: ${connection.responseCode}" // Get response code. 200 means all clear println "Request Method: ${connection.getInputStream()}" //Extract the results |
If you run the script above, you should get the results below:
You essentially get the XML source code from that URL as the result set.
Now, if we add all the components together, our extremely simplistic code might look like:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
// Enter username, pwd username="unlkadmin" password="unlkpwd" // Credentials for basic authorization need to be passed through as username:pwd userCredentials = username + ":" + password; // Basic authorization is set up, but the encoding for credentials need to be changed. basicAuth = "Basic " + javax.xml.bind.DatatypeConverter.printBase64Binary(userCredentials.getBytes()) // Complete URL variable address = "http://unlk.cube.com:19000/profitability/rest/v1/applications" urlInfo = address.toURL() // Variable converted to URL connection = urlInfo.openConnection() // Connection opened connection.setRequestProperty("Content-Type", "application/json"); // Content-type provided to the URL connection.setRequestProperty("Authorization", basicAuth); // Basic auth specified and credentials passed println "Connection Class: ${connection.class}" // Which class is used in the connection println "Response Code/Message: ${connection.responseCode}" // Response code. We need 200 println "Request Results: ${connection.getInputStream()}" // The output from the API |
And, if we execute it, we get the results, in JSON format:
The result set contains a list of all HPCM application names, types and status messages. While this is an extremely simple REST example, the point here is to outline how Groovy and REST can be combined to streamline some of your automation requirements. This code can be wrapped around DOS/Shell/ODI. You can also perform tasks like execute calculations, run dimension builds and data loads (on PBCS) etc. We will look at other examples in later posts.
