List All Planning Units

You can use REST APIs to return a list of planning units for the specified application and owned by the user initiating the REST API. (Note that this does not return all planning units for all applications and users.)

Paging is supported if the optional offset and limit parameters are provided.

Required Roles

Service Administrator

REST Resource

POST

/HyperionPlanning/rest/{version}/applications/{application}/planningunits?q={"scenario":"scenarioName","version":"versionName"}&offset=10&limit=10

Request

Supported Media Types: application/x-www-form-urlencoded

Parameters:

The following table summarizes the client request.

Table 8-52 Parameters

Name	Description	Type	Required	Default
api_version	Version of the API you are developing with	Path	Yes	None
application	The name of the application	Path	Yes	None
q	Paging options for planning units. Possible values are described in the following rows.	Query	No	Limit = 25
scenario	Scenario for the application; required	Query	No	None
version	Version for the application; required	Query	No	None
offset	Indicates the actual index from which the records are returned; 0 based.	Query	No	1
limit	Controls how many items to return; defaults to 25 if not specified.	Query	No	25

Request Payload:

The following table summarizes the payload parameters.

Table 8-53 Parameters

Name	Description	Type	Required
filter	Name, type, and values to filter on. Example: filter={name:"SubStatus",type:3,values:[0,4]}	Payload	No

Example URL and Payload

https://<BASE-URL>/HyperionPlanning/rest/{version}/applications/{application}/planningunits?q={"scenario":"scenarioName","version":"versionName"}&offset=10&limit=10

Example without filters:

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/PS4app1/planningunits?q={"scenario":"Forecast","version":"BU Version_1"}

Example with two filters, multiple values provided:

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/PS4app1/planningunits?q={"scenario":"Forecast","version":"BU Version_1"}

Payload:

filter={name:"Status",type:4,values:[2,5]}&filter={name:"SubStatus",type:3,values:[0,4]}

Response

Supported Media Types: application/json

Parameters:

Table 8-54 Parameters

Name	Description
name	Planning unit name, such as Marketing
value	Planning unit value
owner	Planning unit owner, such as Admin
version	Planning unit version, such as BU Version_1
entity	Planning unit entity, such as Marketing
status	Planning unit status, such as Under Review
scenario	Planning unit scenario, such as Forecast
Formatted value	Formatted value, if any
puName	Planning unit name, such as Marketing
subStatus	Planning unit substatus
secMember	Secondary dimension member, if any
puAlias	Planning unit alias, such as Marketing
versionAlias	Version alias, if any

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "items": [{
        "name": null,
        "value": -1.0,
        "owner": "admin",
        "version": "BU Version_1",
        "entity": "Marketing",
        "status": "Under Review",
        "scenario": "Forecast",
        "formattedValue": "",
        "puName": "Marketing",
        "subStatus": "",
        "secMember": null,
        "puAlias": "Marketing",
        "scenarioAlias": null,
        "versionAlias": null,
        "puId": 50410,
        "links": [{
            "rel": "promotion-path",
            "href": "https://<BASE-URL>/HyperionPlanning/rest/v3/applications/PS4app1/planningunits/%22Forecast%22::%22BU%20Version_1%22::%22Marketing%22::%22%22/promotionpath",
            "action": "GET"
        }, {
            "rel": "annotations-and-history",
            "href": "https://<BASE-URL>/HyperionPlanning/rest/v3/applications/PS4app1/planningunits/%22Forecast%22::%22BU%20Version_1%22::%22Marketing%22::%22%22/historyandannotations?q=%7B%22annotSeq%22:-1,%22logSeq%22:-1%7D",
            "action": "GET"
        }, {
            "rel": "actions",
            "href": "https://<BASE-URL>/HyperionPlanning/rest/v3/applications/PS4app1/planningunits/%22Forecast%22::%22BU%20Version_1%22/actions",
            "action": "POST",
            "data": {
                "pmMembers": "Marketing"
            }
        }, {
            "rel": "change-status",
            "href": "https://<BASE-URL>/HyperionPlanning/rest/v3/applications/PS4app1/planningunits/%22Forecast%22::%22BU%20Version_1%22::%22Marketing%22::%22%22/actions/6",
            "action": "POST",
            "data": {
                "pmMembers": "Marketing",
                "comments": "comments"
            }
        }]
    }],
    "links": [{
        "rel": "self",
        "href": "https://<BASE-URL>/HyperionPlanning/rest/v3/applications/PS4app1/planningunits?q=%7Bscenario:%22Forecast%22,version:%22BU+Version_1%22%7D",
        "action": "POST",
        "data": {
            "filter": [{
                "name": "Status",
                "type": 4,
                "values": [2, 5],
                "defIndex": 0
            }, {
                "name": "SubStatus",
                "type": 3,
                "values": [0, 4],
                "defIndex": 0
            }]
        }
    }],
    "type": "HP"
}