The recent EPM monthly updates brought a few great REST API enhancements. With new classes added to the Groovy library, it is now possible to interact with external web recourses. This surely creates tons of potentials for EPM planning solutions.
Recent Patches
Firstly, let’s take a step back and see what exactly got updated for REST API during the past few months.
The July 2019 patch added the ability to call external rest resources from a groovy object model.
“Planning Groovy object model APIs have been enhanced with the ability to call external REST APIs.”
The following August, September, and October patches have enhanced the REST APIs abilities for Planning, Financial Consolidation and Close, Profitability and Cost Management, Account Reconciliation and Enterprise Data Management.
With the recent patches, what really changes the EPM design and make calling external web possible is the Connection class.
The Connection represents a communications link between the Groovy and an HTTP/HTTPS resource. To create an on-demand connection, you can use:
Connection connection = connection(“http://server:port/HyperionPlanning/rest/v3/applications/Vision”, “user”, “password”)
For more Groovy rules Java API related topics, please check EPM Cloud Groovy Rules Java API Reference.
Background Info
Using REST API in Groovy business rule is similar to how EPM Automate developed. In fact, EPM Automate is built on top of REST API. With the new Groovy functionality, we can call EPM Automate REST recourses from planning Groovy business rules.
Also, with the EPM cloud new SKUs, both Standard and Enterprise versions can create unlimited planning instances. Having Groovy rules to call other planning applications to process data integration and other admin/power user activities come in very handy.
Supported Solutions
Currently, we are able to use REST API for the following cloud services:
- Planning
- Financial Close
- Account Reconciliation
- Profitability and Cost Management
- Tax Reporting
Use Cases
Since connections can be used in Groovy business rules, and Groovy business rules can be used on forms right-click menus and task lists.
Sample right-click menus options and task list activities could be:
- Set application to admin mode
- Set application to user mode
- Refresh Database
- Run Data Map
- Run ASO Aggregation
- Run Snapshot backup
- Copy snapshot across instances
- Set maintenance Time
- Data management – Import Actuals
- Import metadata
- And more….
REST API Client
To start using REST API, I highly suggest you using REST client to test your solution first. Then translate that to a Planning Groovy business rule.
Suggested clients:
- RESTED
- Advance REST
- Postman
- Insomnia
We can call a REST API against the same planning instance. GET the basic information from the application. For example, use Get request against a Planning application.
We will get the following response from the Planning server, which includes the basic application information.
Some sample basic requests and I will discuss them in a future post.
- GET – Retrieve information about the REST API resource
- POST – Create a REST API resource
- PUT – Update a REST API resource
- DELETE – Delete a REST API resource or related component
Groovy Rules
Once you have tested the connection through REST clients, translate the logic to a Groovy business rule. For example, use a Groovy business rule to get application information. We will be able to see the detailed log from the job console.
Considerations
- The use of REST API is based on Groovy which is only available in Enterprise Planning Cloud
- The password in connections has to be manually updated every 120 days
- Only service administrator accounts can define connections
- Testing REST API through REST clients first will help you prepare the related Groovy rules
This is a good start for now. Hopefully, you have some ideas on REST APIs and use cases. In the Part 2 section, I will be focusing on Planning solution itself and disusing using Planning Groovy business rules to call REST APIs.
I do feel this creates so many possibilities for Planning applications and changes solution designs. I hope you enjoy this topic. I will see you in the next post.