Update a Scenario

Updates the supplied scenario properties.

Omitted or null properties retain their current values. A blank description clears the description. For a resulting inheritanceMethod of INHERITS or INPUT_ONLY, a supplied accounts list replaces the scenario's complete account membership; an empty array removes all account members. Supplied accounts must exist and support input versions. STANDALONE rejects any non-null accounts list. When name is supplied and differs from the scenario path parameter, the scenario is renamed. The response returns the complete updated scenario representation. The resulting INHERITS scenario requires an existing, non-blank parentScenario, which may be retained from the current scenario. Non-null parentScenario and inheritedScenarios values are rejected for INPUT_ONLY and STANDALONE. The resulting INPUT_ONLY scenario requires useActuals=NEVER. Invalid inheritance combinations or accounts that do not support input versions return HTTP 422. Unknown referenced scenarios or account IDs return HTTP 404.

Required Roles

Service Administrator

REST Resource

PATCH /HyperionPlanning/rest/sm/v1/applications/{application}/models/{model}/scenarios/{scenario}

Request

Parameters:

Table 3-729 Parameters

Name Description Type Required Default
name Optional new scenario name. When different from the path scenario name, renames the scenario. Minimum length: 1 Path No None
description Optional scenario description. Null omits the update; an empty or whitespace-only value clears the description. Path No None
inheritanceMethod The scenario inheritance method. Values are accepted case-insensitively; INPUT ONLY is also accepted. Path Yes None
useActuals Optional actuals usage method. The resulting value must be NEVER when the resulting inheritanceMethod is INPUT_ONLY. Path No None
parentScenario Optional existing parent scenario name. When the resulting inheritanceMethod is INHERITS, a non-blank parent must be supplied or retained from the existing scenario. A non-null value is rejected for INPUT_ONLY and STANDALONE. Path No None
inheritedScenarios Optional ordered list of existing inherited scenario names. A non-null list, including an empty list, is allowed only when the resulting inheritanceMethod is INHERITS; otherwise it is rejected. Path No None
accounts Complete replacement list of existing account IDs that support input versions. Allowed for INHERITS and INPUT_ONLY: null or omission keeps current accounts, and an empty list removes all account members. Any non-null list, including an empty list, is rejected when the resulting inheritanceMethod is STANDALONE. Path No None

Example URL:

https://<BASE-URL>/HyperionPlanning/rest/sm/v1/applications/Sample/models/M1/scenarios/Base

Request body

{
  "name": "Upside Case 3",
  "description": "Upside Case Scenario description",
  "accounts": [
    "v2000",
    "v1000"
  ]
}

Response

Supported Media Types: application/json

Table 3-730 Parameters

Name Description
name Name of the scenario.
description Description of the scenario.
inheritanceMethod Method the scenario uses to inherit values.
useActuals Setting that controls whether the scenario uses actual data.
parentScenario Name of the scenario’s parent scenario.
accounts Account IDs associated with the scenario.
inheritedScenarios Additional scenarios from which this scenario inherits, in order; empty here.
inheritanceSequence Sequence of scenario inheritance, shown from this scenario to its parent.
isBase Indicates whether this is the base scenario.
isActual Indicates whether this is an actuals scenario.
links Links related to the scenario.
links[].href URL of the linked resource.
links[].action HTTP method for the link.
links[].rel Relationship of the link to the scenario, such as canonical.
links[].data Additional link data, if provided; null in this example.

Example of Response body

{
  "name": "Upside Case 3",
  "description": "Upside Case Scenario description",
  "inheritanceMethod": "INHERITS",
  "useActuals": "NEVER",
  "parentScenario": "Base",
  "accounts": [
    "v1000",
    "v2000"
  ],
  "inheritedScenarios": [],
  "inheritanceSequence": "Upside Case 3->Base",
  "isBase": false,
  "isActual": false,
  "links": [
    {
      "href": "https://<BASE-URL>/HyperionPlanning/rest/sm/v1/applications/Sample/models/M3/scenarios/Upside%20Case%203",
      "action": "GET",
      "rel": "canonical",
      "data": null
    }
  ]
}

Table 3-731 Status Codes

Code Description
400 Invalid request, malformed query JSON, invalid parameter, or service validation failure.
401 Authentication is required.
403 The authenticated caller is not authorized.
404 Application or requested sub-resource was not found.
422 The required scenario or period query parameter is missing or empty.
500 Unexpected server error.

Sample cURL Command

curl -X PATCH -u '<USERNAME>:<PASSWORD>' -H 'Content-Type: application/json' --data '{"name":"Upside Case 3","description":"Upside Case Scenario description","accounts":["v2000","v1000"]}' 'https://<BASE-URL>/HyperionPlanning/rest/sm/v1/applications/Sample/models/M1/scenarios/Base'