Get form definition

Returns the saved form metadata and resolved grid definition by form name or wrapped UUID.

Required Roles

Service Administrator

REST Resource

GET /HyperionPlanning/rest/v3/applications/{appname}/formdefinitions/{idorname}

Request

Parameters:

Table 3-481 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
includeDimensionProperties When true, include saved axis dimension properties and apply-dimension property metadata. query No false
includeSegmentProperties When true, include saved segment properties, row segment dimension properties, and apply-segment property metadata. query No false
includeAllProperties When true, include both saved dimension and segment display-property groups. This is not an all-fields projection switch; exclusion-bearing segments still use object syntax when the flag is false. query No false

No request body is defined for this operation.

For dimension and segment field definitions, see Enriched axis properties in this topic.

The inclusion flags control saved dimension and segment display metadata; they are not general field-projection switches. Setting all three flags to false does not force every segment into matrix syntax. If a segment has exclusions, GET returns a segment object containing members and the applicable exclude or excludeAll matrices to preserve those selections.

By default, axis dimensions are returned as names and ordinary segments are returned as member matrices. Segments with exclusions use objects to preserve members, exclude, and excludeAll, even when the display-property inclusion flags are false. Use includeDimensionProperties=true to include saved dimension-level properties and applyDimensionProperties. Use includeSegmentProperties=true to include saved segment-level properties, row segment dimension properties, and applySegmentProperties. Use includeAllProperties=true to include both property groups. Unset, unavailable, or default-valued properties may be omitted from GET responses. smartPushes and smartPushOptions are returned only when the form has at least one smart push association.

Example URL

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/RevenueCompactForm?includeDimensionProperties=false&includeSegmentProperties=false&includeAllProperties=false

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.

GET https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions/Revenue%20Input
GET 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 the form definition; saved optional settings may be omitted as described below.

Unset, unavailable, or default-valued properties may be omitted. Both smartPushes and smartPushOptions are omitted when the form has no Smart Push associations. The inclusion flags expose saved dimension and segment display settings; they do not make every property unconditional. See Enriched axis properties and Enriched layout example for the enriched response structure.

Supported Media Types: application/json

Table 3-482 Response Parameters

Name Description
id String. The form identifier wrapped as a UUID string.
name The name of the form.
parentId String. The parent folder identifier wrapped as a UUID string. GET returns parentId; parentPath is a request lookup alternative and is not populated in this response.
cubeName The name of the cube associated with the form or data grid.
description A description of the form.
instructions The instructions displayed to users of the form.
hidden Whether the form is hidden.
gridDefinition Form grid layout, suppression flags, axis definitions, and optional enriched axis metadata.
gridDefinition.suppressMissingBlocks Indicates whether to suppress missing data blocks.
gridDefinition.suppressMissingRows Indicates whether to suppress rows containing missing values.
gridDefinition.suppressMissingColumns Indicates whether to suppress columns containing missing values.
gridDefinition.suppressMissingRowsNative Indicates whether to use native missing-row suppression.
gridDefinition.suppressMissingSuppressesZero Indicates whether missing-value suppression also suppresses zero values.
gridDefinition.suppressInvalidScenarioTps Indicates whether to suppress invalid scenario time periods.
gridDefinition.suppressInvalidColumns Indicates whether to suppress invalid columns.
gridDefinition.suppressInvalidRows Indicates whether to suppress invalid rows.
gridDefinition.povAxisDefinition object. POV dimensions and one member string per dimension.
gridDefinition.pageAxisDefinition object. Page dimensions and dimension-aligned member-selection arrays.
gridDefinition.rowAxisDefinition object. Row dimensions and compact member matrices or enriched segment objects.
gridDefinition.columnAxisDefinition object. Column dimensions and compact member matrices or enriched segment objects.
gridDefinition.predictionSupportForDynCalcMbrs boolean. Prediction support for dynamic calculation members, when available.
gridDefinition.autoCorrectSegments boolean. Whether automatic segment correction is enabled, when available.
businessRules array of objects. Associated business rules and rulesets.
businessRules[].name string. Business rule or ruleset name.
businessRules[].type string. RULE or RULESET.
businessRules[].planTypeName string. Plan-type name for a RULE association; omitted for RULESET.
businessRules[].launchEvents array of strings. Configured launch events: beforeLoad, afterLoad, beforeSave, afterSave.
businessRules[].hidePrompts boolean. Whether runtime prompts are hidden.
businessRules[].useMembersOnForm boolean. Whether form members supply runtime-prompt context.
smartPushOptions object. Form-level Smart Push execution options. Omitted when there are no Smart Push associations.
smartPushOptions.runAfterSaveAsynchronously boolean. Whether form Smart Pushes run asynchronously after save.
smartPushOptions.suppressMissingRowsNative boolean. Whether Smart Push uses native missing-row suppression.
smartPushes array of objects. Smart Push associations. Omitted when there are no Smart Push associations.
smartPushes[].name string. Associated data map or Smart Push name.
smartPushes[].runAfterSave boolean. Whether this Smart Push runs after saving the form.
smartPushes[].dimensionOptions array of objects. Per-dimension Smart Push context and selection settings.
smartPushes[].dimensionOptions[].dimension string. Source dimension name.
smartPushes[].dimensionOptions[].useFormContext boolean. Whether to use form context for this dimension.
smartPushes[].dimensionOptions[].selection string. Member-selection expression when form context is not used.
smartPushes[].dimensionOptions[].excludeSelection string. Exclusion expression when form context is not used.
customMenus array of objects. Associated custom menus in stored menu order.
customMenus[].name string. Existing custom-menu name.

Sample Response

This illustrative response shows the form from the Create form definition example, RevenueCompactForm, with its complete POV, page, row, and column layout. UUID values are illustrative. Unset or default-valued metadata may be omitted. The form has no Smart Push associations, so neither smartPushes nor smartPushOptions is returned.

{
  "id": "4f6d4cb0-7b4f-1000-8c0a-fc0f00000051",
  "name": "RevenueCompactForm",
  "parentId": "4f6d4cb0-7b4f-1000-8c0a-fc0f00000000",
  "cubeName": "Plan1",
  "description": "Compact grid-definition example",
  "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"
        ]
      ]
    }
  }
}

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-483 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-484 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-485 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-486 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-487 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.

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.

Create the example form, then retrieve its enriched layout.

POST https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/formdefinitions
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"
        ]
      ]
    }
  }
}

Response with associations

This separate illustrative excerpt assumes that the existing Calculate Revenue rule, Revenue to Reporting Smart Push, and Revenue Actions custom menu have subsequently been associated with RevenueCompactForm. These associations are not created by the minimal Create example. The identity, parent folder, cube, and layout fields are omitted here only to focus on the association structure.

{
  "name": "RevenueCompactForm",
  "businessRules": [
    {
      "name": "Calculate Revenue",
      "type": "RULE",
      "planTypeName": "Plan1",
      "launchEvents": [
        "afterSave"
      ],
      "hidePrompts": true,
      "useMembersOnForm": true
    }
  ],
  "smartPushOptions": {
    "runAfterSaveAsynchronously": true
  },
  "smartPushes": [
    {
      "name": "Revenue to Reporting",
      "runAfterSave": true,
      "dimensionOptions": [
        {
          "dimension": "Account",
          "useFormContext": true
        }
      ]
    }
  ],
  "customMenus": [
    {
      "name": "Revenue Actions"
    }
  ]
}

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-488 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-489 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-490 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-491 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-492 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-493 Error cases

HTTP outcome Condition Action
400 Bad Request Invalid request parameter values. 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.