Replace form definition
Replaces a simple form definition identified by id or name. The request must provide the full required replacement payload. The replacement grid definition may use legacy axes or enriched dimension and segment objects.
This operation replaces an existing form definition and rebuilds its grid layout. It does not create a form if the target does not exist; a missing target returns HTTP 404.
Include the metadata and associations that you want to retain in the replacement request.
Omitting description or instructions clears the saved
value. Omitting hidden sets it to false. Supplied
business-rule, Smart Push, and custom-menu association lists replace the saved lists;
omitted lists remove the corresponding authored associations. Native form calculations
are retained separately.
To preserve existing enriched dimension and segment settings, first retrieve the form
definition using GET with includeAllProperties=true, and use the returned
settings to construct the complete replacement request. A default GET response may omit
saved dimension and segment display settings.
Use Update form definition (PATCH) for isolated changes instead of replacing the complete definition.
Required Roles
Service Administrator
REST Resource
PUT /HyperionPlanning/rest/v3/applications/{appname}/formdefinitions/{idorname}
Request
For supported top-level properties, JSON types, conditional requirements, and operation-specific behavior, see Form-definition request properties in this topic.
Parameters:
Table 3-508 Request Parameters
| Name | Description | Type | Required | Default |
|---|---|---|---|---|
appname
|
The name of the application. | path | Yes | None |
idorname
|
Form id wrapped as a UUID string or the form name. | path | Yes | None |
name
|
The name of the form. | payload (string) | Yes | None |
parentId |
The wrapped UUID of an existing parent form folder. If nonempty, takes precedence over parentPath.
|
payload (string) | Required if parentPath is omitted or empty.
|
None |
parentPath |
The path of an existing parent form folder, such as /Library. Used when parentId is omitted or empty.
|
payload (string) | Required if parentId is omitted or empty.
|
None |
cubeName
|
The name of the cube associated with the form or data grid. | payload (string) | Yes | None |
description
|
A description of the form. | payload (string) | Optional | None |
gridDefinition
|
Form grid layout, suppression flags, axis definitions, and optional enriched axis metadata. | payload (object) | Yes | None |
gridDefinition.povAxisDefinition |
The POV axis definition. Include this object when the form layout uses this axis. | payload (object) | Required when the form layout uses the POV axis. | None |
gridDefinition.povAxisDefinition.dimensions |
The dimensions assigned to the POV axis, in the same order as their member selections. Use dimension-name strings in the compact syntax or supported dimension objects in the enriched syntax. Do not mix strings and objects within one axis. | payload (array) | Required when povAxisDefinition is supplied; the array must not be empty. | None |
gridDefinition.povAxisDefinition.members |
One member string for each POV dimension, in dimension order. For example, ["Working", "USD"] corresponds to dimensions ["Version", "Currency"]. The outer count must match dimensions. Singleton nested lists are accepted for compatibility; use strings in new examples. POV exclusions are not supported. | payload (array of strings) | Required when povAxisDefinition is supplied. | None |
gridDefinition.rowAxisDefinition |
The row axis definition. Include this object when the form layout uses this axis. | payload (object) | Required when the form layout uses the row axis. | None |
gridDefinition.rowAxisDefinition.dimensions |
The dimensions assigned to the row axis, in the same order as their member selections. Use dimension-name strings in the compact syntax or supported dimension objects in the enriched syntax. Do not mix strings and objects within one axis. | payload (array) | Required when rowAxisDefinition is supplied; the array must not be empty. | None |
gridDefinition.rowAxisDefinition.segments |
An array of segments. In compact syntax, each segment is a member matrix with one member-selection array per axis dimension. In enriched syntax, each segment is an object containing members and supported metadata. The members matrix has the same dimension order and count as dimensions. Do not mix matrix and object segments within one axis. | payload (array) | Required when rowAxisDefinition is supplied. | None |
gridDefinition.rowAxisDefinition.segments[].members |
The member matrix of an enriched segment: one member-selection array per axis dimension, in dimension order. For dimensions ["Account", "Entity"], an example is [["Revenue"], ["North America"]]. In compact syntax, the segment itself is this matrix. | payload (array of arrays of strings) | Required for each enriched segment object. | None |
gridDefinition.columnAxisDefinition |
The column axis definition. Include this object when the form layout uses this axis. | payload (object) | Required when the form layout uses the column axis. | None |
gridDefinition.columnAxisDefinition.dimensions |
The dimensions assigned to the column axis, in the same order as their member selections. Use dimension-name strings in the compact syntax or supported dimension objects in the enriched syntax. Do not mix strings and objects within one axis. | payload (array) | Required when columnAxisDefinition is supplied; the array must not be empty. | None |
gridDefinition.columnAxisDefinition.segments |
An array of segments. In compact syntax, each segment is a member matrix with one member-selection array per axis dimension. In enriched syntax, each segment is an object containing members and supported metadata. The members matrix has the same dimension order and count as dimensions. Do not mix matrix and object segments within one axis. | payload (array) | Required when columnAxisDefinition is supplied. | None |
gridDefinition.columnAxisDefinition.segments[].members |
The member matrix of an enriched segment: one member-selection array per axis dimension, in dimension order. For dimensions ["Account", "Entity"], an example is [["Revenue"], ["North America"]]. In compact syntax, the segment itself is this matrix. | payload (array of arrays of strings) | Required for each enriched segment object. | None |
gridDefinition.pageAxisDefinition |
The page axis definition. Include this object when the form layout uses this axis. | payload (object) | Required when the form layout uses the page axis. | None |
gridDefinition.pageAxisDefinition.dimensions |
The dimensions assigned to the page axis, in the same order as their member selections. Use dimension-name strings in the compact syntax or supported dimension objects in the enriched syntax. Do not mix strings and objects within one axis. | payload (array) | Required when pageAxisDefinition is supplied; the array must not be empty. | None |
gridDefinition.pageAxisDefinition.members |
One member-selection array for each page dimension, in dimension order. For example, [["Actual", "Budget"], ["USD"]] corresponds to dimensions ["Scenario", "Currency"]. The outer count must match the nonempty dimensions array. | payload (array of arrays of strings) | Required when pageAxisDefinition is supplied. | None |
Send a required request body with Content-Type: application/json.
Specify at least one nonempty parent-folder reference: parentId or
parentPath. The referenced folder must already exist and be accessible to
the caller. If both references are nonempty, parentId takes precedence.
This example assumes that the /Library folder exists and is accessible
to the caller.
Include the axes used by the form layout and provide selections for every required cube dimension. Assign each dimension to only one axis. Within each axis, keep dimensions and member-selection arrays in the same order.
POV members use one string per dimension. Page members use one array of selections per
dimension. Each compact row or column segment is a member matrix; each enriched segment
is an object with a members matrix and supported metadata. For example,
a compact segment [["Revenue"], ["North America"]] corresponds to
dimensions ["Account", "Entity"]; its enriched equivalent is
{"members":[["Revenue"],["North America"]]}.
An included page axis must have nonempty dimensions and a matching number
of outer members entries. POV exclusions are rejected. Formula segments
are not supported for form-definition authoring.
Example request body:
{
"name": "RevenueForm_Replaced",
"parentPath": "/Library",
"cubeName": "Plan1",
"description": "Replacement form definition",
"gridDefinition": {
"povAxisDefinition": {
"dimensions": [
"Version",
"Product",
"Currency",
"Entity"
],
"members": [
"Working",
"P_TP",
"USD",
"TD"
]
},
"rowAxisDefinition": {
"dimensions": [
"Account"
],
"segments": [
{
"members": [
[
"Statistics"
]
]
}
]
},
"columnAxisDefinition": {
"dimensions": [
"Years",
"Period"
],
"segments": [
{
"members": [
[
"FY15"
],
[
"Jan"
]
]
}
]
},
"pageAxisDefinition": {
"dimensions": [
"Scenario"
],
"members": [
[
"Actual"
]
]
}
}
}
Form-definition request properties
The following reference covers the 12 writable top-level properties supported by Create (POST), Replace (PUT), and Update (PATCH) form definition.
For PATCH, supply at least one recognized property with a nonnull value. An empty object
or a request containing only null recognized properties is rejected. For example,
{"description":""} clears the description, while
{"description":null} alone is not a valid update.
The response property id is not a writable request property. For PUT and
PATCH, identify the target form using idorname in the path; a body
id does not replace that path parameter.
Table 3-509 Writable form-definition properties
| Name | JSON Type | Description and conditions | Create (POST) | Replace (PUT) | Update (PATCH) |
|---|---|---|---|---|---|
| name | string | The form name. | Required; no default. | Required; supplies the replacement name. | Optional; omission/null preserves the saved name. |
| cubeName | string | The cube associated with the form grid. | Required; no default. | Required; supplies the cube for the replacement layout. | Optional; omission/null preserves the saved value. |
| parentId | string | The wrapped UUID of an existing accessible parent form folder. A nonempty value takes precedence over parentPath. | Supply a nonempty parentId or parentPath; no default folder. | Supply a nonempty parentId or parentPath; no default folder. | Optional; omission/null preserves the saved parent unless parentPath is supplied. |
| parentPath | string | The path of an existing accessible parent form folder, such as /Library. Used when parentId is omitted or empty. | Supply a nonempty parentId or parentPath; no default folder. | Supply a nonempty parentId or parentPath; no default folder. | Optional; supplies a parent-folder lookup alternative. Omit both parent references to preserve the saved parent. |
| description | string | A description of the form. | Optional; no description if omitted. | Optional; omission clears the saved description. | Optional; omission/null preserves the saved description. An empty string clears it. |
| instructions | string | Instructions associated with the form. | Optional; no instructions if omitted. | Optional; omission clears the saved instructions. | Optional; omission/null preserves the saved instructions. |
| hidden | boolean | Whether the form is hidden. | Optional; defaults to false. | Optional; omission sets hidden to false. | Optional; omission/null preserves the saved value. Supply true or false to change it. |
| gridDefinition | object | The complete intended grid layout, including its axes and supported grid settings. | Required; no default layout. | Required; rebuilds the grid from the supplied layout. | Optional; omission/null preserves the layout. A supplied object rebuilds the grid; it is not a recursive merge. |
| businessRules | array | Business-rule and ruleset associations. RULE associations require planTypeName; RULESET associations omit it. Referenced artifacts must already exist. | Optional; no authored rule associations if omitted. | Optional; replaces the authored rule associations. Omission removes them; native form calculations are retained separately. | Optional; omission/null preserves the list. An empty array clears it; a supplied list replaces it. |
| smartPushOptions | object | Form-level Smart Push options, including runAfterSaveAsynchronously and suppressMissingRowsNative. | Optional; supplies form-level options when provided. | Optional; include the intended options when replacing Smart Push associations. | Optional; omission/null preserves saved options. Supply an object to set form-level options. |
| smartPushes | array | Smart Push associations with existing artifacts and their save/context settings. | Optional; no Smart Push associations if omitted. | Optional; replaces the Smart Push association list. Omission removes the associations. | Optional; omission/null preserves the list. An empty array clears it; a supplied list replaces it. |
| customMenus | array | Custom-menu associations using existing menu names. List order determines menu order. | Optional; no custom-menu associations if omitted. | Optional; replaces the custom-menu association list. Omission removes the associations. | Optional; omission/null preserves the list. An empty array clears it; a supplied list replaces it. |
Example URL
https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/RevenueForm
Form names in URLs
Percent-encode a form name when it appears as a URL path segment. Encode spaces as
%20 and reserved characters that are part of the name, such as
# as %23 and ? as %3F.
Encoding preserves characters in a valid form name; it does not make an invalid name valid.
Do not encode the path separators or encode an already encoded name a second time.
The following alternative URLs illustrate addressing a form named Revenue Input by encoded name or by its corresponding wrapped UUID. Substitute the actual form identifier.
PUT https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/Revenue%20Input
PUT https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/4f6d4cb0-7b4f-1000-8c0a-fc0f00000053
Copy URLs and JSON directly from the code blocks. Display wrapping does not add whitespace to the underlying URL or JSON string value.
Response
Success: 200 OK. Returns an id/name/self-link reference for the replaced form. Use GET to inspect the saved definition.
Supported Media Types: application/json
Table 3-510 Response Parameters
| Name | Description |
|---|---|
id
|
The unique identifier of the form. |
name
|
The name of the form. |
links
|
Links to this resource and related operations. |
links[].rel
|
The relationship of the linked resource to this resource. |
links[].href
|
The URL of the linked resource. |
links[].action
|
The HTTP method used to access the linked resource. |
Sample Response
The following shows an example response.
{
"id": "4f6d4cb0-7b4f-1000-8c0a-fc0f00000051",
"name": "RevenueForm_Replaced",
"links": [
{
"rel": "self",
"href": "https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/4f6d4cb0-7b4f-1000-8c0a-fc0f00000051",
"action": "GET"
}
]
}
Enriched axis properties
Use dimension objects in an axis dimensions array to specify display
settings. Use segment objects in a row or column segments array to specify
member selections and segment settings. Do not mix string and object dimension entries
within one axis, or matrix and object segment entries within one axis.
Dimension objects apply to POV, page, row, and column axes. Segment objects apply to row
and column axes. Segment dimensionProperties are supported only on rows.
The properties object belongs inside its segment, and the apply-to-all
objects belong directly inside their axis.
Table 3-511 Enriched dimension object: dimensions[]
| Property | JSON Type | Description |
|---|---|---|
name |
string | Required. The dimension name. |
hidden |
boolean | Hide the dimension label on the form. |
displayName |
boolean | Display member names for the dimension. |
displayAlias |
boolean | Display member aliases for the dimension. |
displayMemberFormula |
boolean | Display member formulas. |
displayMemberFormulaDescription |
boolean | Display member formula descriptions. |
drillOnSharedMembers |
boolean | Drill on shared members using base members. |
startExpanded |
boolean | Start the dimension expanded. |
dimensionWidth |
integer | Dimension display width. |
showCurrency |
boolean | Display currency for the dimension. |
showQualifiedName |
string | Qualified-name display option: never, asNeeded, or always. |
allowFlexibleDefinition |
boolean | Allow flexible definition for the dimension. |
displayConsolidationOperators |
boolean | Display consolidation operators. |
Table 3-512 Enriched segment object: segments[]
| Property | JSON Type | Description |
|---|---|---|
members |
array of arrays of strings | Required. Member selections aligned with the axis dimension order. |
exclude |
array of arrays of strings | Optional member selections to exclude, aligned with the axis dimensions. |
excludeAll |
array of arrays of strings | Optional all-member exclusion selections, aligned with the axis dimensions. |
properties |
object | Optional segment display, read-only, suppression, and sizing settings listed below. |
dimensionProperties |
array of objects | Optional per-dimension settings for row segments only. Each entry requires dimension and can specify enableDropdown. |
Table 3-513 Segment settings: segments[].properties
| Property | JSON Type | Description |
|---|---|---|
hidden |
boolean | Hide the segment. Default: false. |
readOnly |
boolean | Mark the segment read only. Default: false. |
suppressMissing |
boolean | Suppress missing values. Default: false. |
suppressInvalidScenarioTps |
boolean | Suppress invalid scenario/time-period combinations. Default: false. |
addSeparator |
boolean | Add a visual separator before the segment. Default: false. |
suppressHierarchy |
boolean | Suppress hierarchy display. Default: false. |
showFormula |
boolean | Show member formulas. Default: false. |
size |
integer | Segment size. |
Table 3-514 Row-only settings: segments[].dimensionProperties[]
| Property | JSON Type | Description |
|---|---|---|
dimension |
string | Required. The name of a dimension on the row axis. |
enableDropdown |
boolean | Enable dropdown member selection for this dimension in the row segment. Default: false. |
Table 3-515 Apply-to-all settings
| Property | JSON Type | Description |
|---|---|---|
applyDimensionProperties |
object | Axis-level settings for copying dimension display properties within the same axis. |
applyDimensionProperties.toAllDimensions |
boolean | Apply properties from the source dimension to all dimensions on this axis. Default: false; when false or omitted, properties apply where specified. |
applyDimensionProperties.sourceDimension |
integer | Zero-based index in the same axis dimensions array. Used when toAllDimensions is true. Default: 0. |
applySegmentProperties |
object | Row- or column-axis settings for copying segment properties within that axis. |
applySegmentProperties.toAllSegments |
boolean | Apply properties from the source segment to all segments on this axis. Default: false; when false or omitted, properties apply where specified. |
applySegmentProperties.sourceSegment |
integer | Zero-based index in the same axis segments array. Used when toAllSegments is true. Default: 0. |
A source index of 0 selects the first dimension or segment in that axis;
1 selects the second. Use an index that identifies an existing entry.
Apply-to-all settings do not copy properties across axes.
Member and exclusion matrices follow the axis dimension order. Page axes also support
dimension-aligned exclude and excludeAll matrices;
POV exclusions are rejected.
For GET, use includeDimensionProperties=true for dimension settings and
apply-dimension metadata, includeSegmentProperties=true for segment
settings and apply-segment metadata, or includeAllProperties=true for
both groups. Unset, unavailable, or default-valued properties may be omitted.
Enriched layout example
The sample assumes that the /Library folder, Plan1 cube, and referenced members exist and are accessible. The cube must have the dimensions shown in the layout. RevenueEnrichedForm must already exist.
These are illustrative request and response examples. The response is an excerpt showing the saved layout; other metadata and default-valued settings may be omitted.
Submit the complete intended layout for the existing form, then retrieve it with all property groups.
PUT https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/RevenueEnrichedForm
Content-Type: application/json
{
"name": "RevenueEnrichedForm",
"parentPath": "/Library",
"cubeName": "Plan1",
"description": "Enriched dimension and segment settings",
"gridDefinition": {
"povAxisDefinition": {
"dimensions": [
{
"name": "Version",
"displayAlias": true
},
{
"name": "Product",
"displayAlias": true
},
{
"name": "Currency",
"displayAlias": true
}
],
"members": [
"Working",
"P_TP",
"USD"
]
},
"rowAxisDefinition": {
"dimensions": [
{
"name": "Account",
"displayAlias": true,
"dimensionWidth": 20,
"showQualifiedName": "always"
},
{
"name": "Entity",
"displayAlias": true
}
],
"segments": [
{
"members": [
[
"Statistics"
],
[
"No Entity"
]
],
"properties": {
"suppressMissing": true,
"size": 6
},
"dimensionProperties": [
{
"dimension": "Account",
"enableDropdown": true
}
]
},
{
"members": [
[
"Price"
],
[
"North America"
]
],
"properties": {
"suppressMissing": true,
"size": 6
}
}
],
"applyDimensionProperties": {
"toAllDimensions": true,
"sourceDimension": 0
},
"applySegmentProperties": {
"toAllSegments": true,
"sourceSegment": 0
}
},
"columnAxisDefinition": {
"dimensions": [
{
"name": "Years",
"displayAlias": true
},
{
"name": "Period",
"displayAlias": true
}
],
"segments": [
{
"members": [
[
"FY15"
],
[
"Jan"
]
],
"properties": {
"readOnly": true,
"size": 4
}
},
{
"members": [
[
"FY16"
],
[
"Feb"
]
],
"properties": {
"readOnly": true,
"size": 4
}
}
]
},
"pageAxisDefinition": {
"dimensions": [
{
"name": "Scenario",
"displayAlias": true
}
],
"members": [
[
"Actual"
]
]
}
}
}
Retrieve the same form with enriched properties:
GET https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/RevenueEnrichedForm?includeAllProperties=true
Illustrative matching GET response excerpt (HTTP 200):
{
"name": "RevenueEnrichedForm",
"cubeName": "Plan1",
"gridDefinition": {
"povAxisDefinition": {
"dimensions": [
{
"name": "Version",
"displayAlias": true
},
{
"name": "Product",
"displayAlias": true
},
{
"name": "Currency",
"displayAlias": true
}
],
"members": [
"Working",
"P_TP",
"USD"
]
},
"rowAxisDefinition": {
"dimensions": [
{
"name": "Account",
"displayAlias": true,
"dimensionWidth": 20,
"showQualifiedName": "always"
},
{
"name": "Entity",
"displayAlias": true,
"dimensionWidth": 20,
"showQualifiedName": "always"
}
],
"segments": [
{
"members": [
[
"Statistics"
],
[
"No Entity"
]
],
"properties": {
"suppressMissing": true,
"size": 6
},
"dimensionProperties": [
{
"dimension": "Account",
"enableDropdown": true
}
]
},
{
"members": [
[
"Price"
],
[
"North America"
]
],
"properties": {
"suppressMissing": true,
"size": 6
}
}
],
"applyDimensionProperties": {
"toAllDimensions": true,
"sourceDimension": 0
},
"applySegmentProperties": {
"toAllSegments": true,
"sourceSegment": 0
}
},
"columnAxisDefinition": {
"dimensions": [
{
"name": "Years",
"displayAlias": true
},
{
"name": "Period",
"displayAlias": true
}
],
"segments": [
{
"members": [
[
"FY15"
],
[
"Jan"
]
],
"properties": {
"readOnly": true,
"size": 4
}
},
{
"members": [
[
"FY16"
],
[
"Feb"
]
],
"properties": {
"readOnly": true,
"size": 4
}
}
]
},
"pageAxisDefinition": {
"dimensions": [
{
"name": "Scenario",
"displayAlias": true
}
],
"members": [
[
"Actual"
]
]
}
}
}
Business-rule, Smart Push, and custom-menu associations
These properties associate existing artifacts with a form. The referenced rules, rulesets, data maps or Smart Pushes, and custom menus must already exist and be accessible. These operations do not create those artifacts.
Use arrays of objects for businessRules, smartPushes,
and customMenus; use an object for smartPushOptions.
Table 3-516 Business-rule association: businessRules[]
| Property | JSON Type | Description |
|---|---|---|
name |
string | Required. Name of an existing business rule or ruleset. |
type |
string | RULE or RULESET. Specify the type explicitly in examples. |
planTypeName |
string | Required for RULE: identifies the plan type where the rule is deployed. Omit for RULESET. |
launchEvents |
array of strings | Supported values: beforeLoad, afterLoad, beforeSave, afterSave. Omit or use [] to associate without automatic launch. |
hidePrompts |
boolean | Hide runtime prompts when this artifact launches from the form. Default: false. |
useMembersOnForm |
boolean | Use form members as runtime-prompt context. Default: false. |
Table 3-517 Form-level Smart Push options: smartPushOptions
| Property | JSON Type | Description |
|---|---|---|
runAfterSaveAsynchronously |
boolean | Run form Smart Pushes asynchronously after save. Default: false. |
suppressMissingRowsNative |
boolean | Use native missing-row suppression for Smart Push execution. Default: false. |
Table 3-518 Smart Push association: smartPushes[]
| Property | JSON Type | Description |
|---|---|---|
name |
string | Required. Existing data map or Smart Push name. |
runAfterSave |
boolean | Run this Smart Push after form save. Default: false. |
dimensionOptions |
array of objects | Optional per-dimension context or selection overrides. Omit to use the Smart Push default configuration. |
Table 3-519 Smart Push dimension options: smartPushes[].dimensionOptions[]
| Property | JSON Type | Description |
|---|---|---|
dimension |
string | Required. Source dimension name. |
useFormContext |
boolean | Use the current form context for this dimension. If omitted, defaults to true when neither selection nor excludeSelection is supplied, and false when either selection property is supplied. |
selection |
string | Member-selection expression used when useFormContext is false. |
excludeSelection |
string | Member-selection expression to exclude when useFormContext is false. |
Table 3-520 Custom-menu association: customMenus[]
| Property | JSON Type | Description |
|---|---|---|
name |
string | Required. Existing custom-menu name. The order of entries in customMenus determines the menu order. |
For PATCH, omitted or null association lists preserve the saved lists; an empty array clears the selected list. A supplied list replaces the complete saved list rather than appending entries. PUT replaces authored associations and removes omitted association lists. Native form calculations are retained separately.
GET returns saved associations when applicable. Both smartPushes and
smartPushOptions are omitted if there are no Smart Push associations.
Default-valued or unset nested properties may be omitted from the response.
Create, retrieve, and update associations
This separate illustrative sequence uses RevenueAssociationsForm in Plan1. The /Library folder, cube dimensions and members, Calculate Revenue rule deployed to Plan1, Revenue Ruleset, Revenue to Reporting data map or Smart Push, and Revenue Actions menu must exist and be accessible. Statistics and Units must be valid Account members for the illustrated Smart Push selections.
Create the form with the existing artifact associations (HTTP 201 on success):
POST https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions
Content-Type: application/json
{
"name": "RevenueAssociationsForm",
"parentPath": "/Library",
"cubeName": "Plan1",
"description": "Form with existing artifact associations",
"gridDefinition": {
"povAxisDefinition": {
"dimensions": [
"Version",
"Product",
"Currency"
],
"members": [
"Working",
"P_TP",
"USD"
]
},
"rowAxisDefinition": {
"dimensions": [
"Account",
"Entity"
],
"segments": [
[
[
"Statistics"
],
[
"No Entity"
]
],
[
[
"Price"
],
[
"North America"
]
]
]
},
"columnAxisDefinition": {
"dimensions": [
"Years",
"Period"
],
"segments": [
[
[
"FY15"
],
[
"Jan"
]
],
[
[
"FY16"
],
[
"Feb"
]
]
]
},
"pageAxisDefinition": {
"dimensions": [
"Scenario"
],
"members": [
[
"Actual"
]
]
}
},
"businessRules": [
{
"name": "Calculate Revenue",
"type": "RULE",
"planTypeName": "Plan1",
"launchEvents": [
"afterSave"
],
"hidePrompts": true,
"useMembersOnForm": true
},
{
"name": "Revenue Ruleset",
"type": "RULESET",
"launchEvents": []
}
],
"smartPushOptions": {
"runAfterSaveAsynchronously": true,
"suppressMissingRowsNative": true
},
"smartPushes": [
{
"name": "Revenue to Reporting",
"runAfterSave": true,
"dimensionOptions": [
{
"dimension": "Account",
"useFormContext": false,
"selection": "ILvl0Descendants(Statistics)",
"excludeSelection": "Units"
}
]
}
],
"customMenus": [
{
"name": "Revenue Actions"
}
]
}
Retrieve that same form with its saved associations:
GET https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/RevenueAssociationsForm
Illustrative matching GET response (HTTP 200). UUIDs are illustrative; default-valued or unset properties may be omitted.
{
"id": "4f6d4cb0-7b4f-1000-8c0a-fc0f00000052",
"parentId": "4f6d4cb0-7b4f-1000-8c0a-fc0f00000000",
"name": "RevenueAssociationsForm",
"cubeName": "Plan1",
"description": "Form with existing artifact associations",
"gridDefinition": {
"povAxisDefinition": {
"dimensions": [
"Version",
"Product",
"Currency"
],
"members": [
"Working",
"P_TP",
"USD"
]
},
"rowAxisDefinition": {
"dimensions": [
"Account",
"Entity"
],
"segments": [
[
[
"Statistics"
],
[
"No Entity"
]
],
[
[
"Price"
],
[
"North America"
]
]
]
},
"columnAxisDefinition": {
"dimensions": [
"Years",
"Period"
],
"segments": [
[
[
"FY15"
],
[
"Jan"
]
],
[
[
"FY16"
],
[
"Feb"
]
]
]
},
"pageAxisDefinition": {
"dimensions": [
"Scenario"
],
"members": [
[
"Actual"
]
]
}
},
"businessRules": [
{
"name": "Calculate Revenue",
"type": "RULE",
"planTypeName": "Plan1",
"launchEvents": [
"afterSave"
],
"hidePrompts": true,
"useMembersOnForm": true
},
{
"name": "Revenue Ruleset",
"type": "RULESET",
"launchEvents": []
}
],
"smartPushOptions": {
"runAfterSaveAsynchronously": true,
"suppressMissingRowsNative": true
},
"smartPushes": [
{
"name": "Revenue to Reporting",
"runAfterSave": true,
"dimensionOptions": [
{
"dimension": "Account",
"useFormContext": false,
"selection": "ILvl0Descendants(Statistics)",
"excludeSelection": "Units"
}
]
}
],
"customMenus": [
{
"name": "Revenue Actions"
}
]
}
Update only the associations on that same form. The Calculate Revenue launch event changes to beforeSave, and Revenue to Reporting no longer runs automatically after save. Include the existing Revenue Ruleset and Revenue Actions entries to retain them in the replaced lists. The omitted layout, metadata, and form-level Smart Push options are preserved.
PATCH https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/RevenueAssociationsForm
Content-Type: application/json
{
"businessRules": [
{
"name": "Calculate Revenue",
"type": "RULE",
"planTypeName": "Plan1",
"launchEvents": [
"beforeSave"
],
"hidePrompts": true,
"useMembersOnForm": true
},
{
"name": "Revenue Ruleset",
"type": "RULESET",
"launchEvents": []
}
],
"smartPushes": [
{
"name": "Revenue to Reporting",
"runAfterSave": false,
"dimensionOptions": [
{
"dimension": "Account",
"useFormContext": false,
"selection": "ILvl0Descendants(Statistics)",
"excludeSelection": "Units"
}
]
}
],
"customMenus": [
{
"name": "Revenue Actions"
}
]
}
Successful PATCH returns HTTP 200. Retrieve the same form again to inspect its saved association settings. These association operations configure lifecycle behavior; they are not requests to execute the rule or Smart Push immediately.
Error responses
For general HTTP status definitions and error-handling guidance, see Error Handling and Status Codes. The operation-specific cases below distinguish authentication, access, input, and missing-resource failures. Inspect the actual error response for diagnostic details.
Table 3-521 Error cases
| HTTP outcome | Condition | Action |
|---|---|---|
| 400 Bad Request | Missing or empty parentId and parentPath; incomplete replacement payload; invalid dimension/member selections. | Correct the request parameters or payload before retrying. |
| 401 Unauthorized | Authentication credentials are missing or invalid. | Authenticate using the supported authentication method. |
| 404 Not Found | The target form does not exist. | Check the application and the form name or wrapped UUID. |
| 500 Internal Server Error | An unexpected server-side failure prevents completion. | Inspect the returned diagnostic details before deciding whether to retry. |