EPM Cloud – Managing journals with REST

I previously put together a series of posts covering journals in EPM Cloud Financial Consolidation and Close. The posts provided an overview of journals and detailed the workflow process before moving on to look at the options for loading journals through the simplified UI and Data Management.

If you have not read the posts and are interested they are available at:

EPM Cloud - Journals and Data Management - Part 1

EPM Cloud - Journals and Data Management - Part 2
EPM Cloud - Journals and Data Management - Part 3
EPM Cloud - Journals and Data Management - Part 4

At the time of writing them there were no options to manage journals through the REST API or EPM Automate. In the ever-evolving world of EPM Cloud, recent functionality has been added which allows you to interact with Journals through the REST API. I am sure related commands will be introduced to EPM Automate in a future release.

It is now possible to carry out the following actions through the REST API.

• Retrieve Journals
• Retrieve Journal line item details
• Submit, Approve, Post, Unpost and Reject Journals
• Open or close Journal periods.

As I have a keen interest in REST and have been covering the rise of the APIs for the last four years, I thought it would be worth having a look at what is currently possible with journals.

I am not going to go through the basics again so there will be an assumption you understand what REST all is about. For demo purposes I will be using a free browser-based REST client and for scripting it will be PowerShell. Please feel free to select your preferred option as I am not suggesting those are the ones to use, you can work with REST APIs in most scripting languages so pick the one that you feel most comfortable with.

To start off, I have created three journals which have the status of “Working”. Workflow is enabled so the journals will need to go through the different states before being posted.

To retrieve the list of journals there is a REST resource available. A GET request can be made against URL format:

https://<cloud_instance>/HyperionPlanning/rest/v3/applications/<app_name>/journals?q=<filter>

The filter, which is in JSON format, defines which journals to return; it must include scenario, year, period and journal status. The status depends if workflow is enabled but the possible values are Working, Submitted, Approved and Posted.

The query filter can also include entity, label, description and group.

To retrieve the journals I have created, I can make a request to the following URL:

https://<cloud_instance>/HyperionPlanning/rest/v3/applications/Vision/journals?q={"scenario":"Actual","year":"FY19","period":"Sep","status": "WORKING"}

Using a REST client this provides a response of

As you can see there is a lot of useful information returned for each journal which can then be processed, for example you could generate a list of journals by label and description which have been posted for the current period.

By default, 5 journals will be returned. This can be controlled by including a limit parameter in the URL. If 10 journals are to be returned the URL could be:

https://<cloud_instance>/HyperionPlanning/rest/v3/applications/Vision/journals?q=<filter>&limit=10

The response will include a maximum of 10 journals.

If there are more journals than the limit, the “hasMore” parameter value will be “true” and you can use “offset” or increase the limit to return the remaining journals.

The journal URL that is returned is a direct link to the journal. If you enter the URL into an authenticated browser it will open the journal and display the line items.

For example:

To convert this into scripting does not require much effort. The following script returns journal for a month which having the “Submitted” status, only the journal label and description are outputted.

The script can be easily updated to output any of the details returned in the response. This information could be processed further or possibly sent to a list of people.

Just to highlight, if you don’t include the status in the filter section of the URL then the response returned is:

If one of the required dimensions is not included in the filter:

This REST resource only provides summary journal information, if you require the line item details then there is another resource available.

A GET request can be made to a similar URL which includes the journal label, the format for this is:

https://<cloud_instance>/HyperionPlanning/rest/v3/applications/<app_name>/journals/<journal_label>?q=<filter>&lineItems=true

If you don’t include the “lineItems” parameter then the default is false, this means it would only return summary information like the previous resource.

The filter must include scenario, year and period.

As an example, let us take the journal “Rent Expense Adjust” which has the following line items.

The URL to retrieve this journal with line item details:

https://<cloud_instance>/HyperionPlanning/rest/v3/applications/Vision/journals/Rent Expense Adjust?q={"scenario":"Actual","year":"FY19","period":"Sep"}&lineItems=true

Using a REST client this returns the following information

Compared to the previous REST resource, the response not only includes the total debit and credit for the journal but also a breakdown of the line items.

I did notice an issue with intercompany being returned as null instead of the member name and a slight spelling mistake with “description”.

In terms of scripting, I have modified my previous example to return journal information including line item details.

Now that I have covered retrieving journal information, let us move on to updating the journal status.

This time the REST resource requires the POST method to a URL with the format:

https://<cloud_instance>/HyperionPlanning/rest/v3/applications/<app_name>/journals/<journal_label>/actions

It also requires parameters in JSON in the body of the request which must include scenario, year, period and action.

The action can be “Submit”, “Reject”, “Approve”, “Post”, “Unpost”

Let us submit the “Rent Expense Adjust” journal which currently has a status of “Working”.

The response will provide details of the new status.

In the UI, the journal now has a status of “Submitted”.

This can easily be replicated by modifying my existing script.

The next step in the workflow would be to approve the journal, what if I try to skip a step and try and post the journal?

An error message is returned to highlight that a journal cannot be posted when it is in the state of “Submitted” as the workflow process must be followed.

If I try to approve the journal and the period is not open, the following error will be returned in the response.

In the UI you can see that period has not been opened.

This leads me nicely on to the final REST resource which provides the ability to open and close periods.

The URL format is:

https://<cloud_instance>/HyperionPlanning/rest/v3/applications/<app_name>/journalPeriods/<period>/actions

Once again this requires a POST method and parameters included the body of the request. The parameters must include scenario, year, period and action.

The action can be either “Open” or “Close”.

An example to open a period would be

Which provides a response to indicate the period is now open.

This can be confirmed in the UI.

An example to close a period using a modified version of the previous script would be

The period will now be closed.

Please note that if you try and close a period which has journals with a status of “Submitted” or “Approved”, then it will look like the period has been closed as the same response will be returned but it will not have been closed.

If you try this in the UI you will be presented with a confirmation message.

I think that about covers the current journal REST API functionality. Until next time…