Validate Ruleset Package Payload
Validates the ruleset package supplied in the request body. VALIDATE_AND_DEPLOY can import or update and deploy its definitions after overall validation success.
Package lifecycle and side effects
Create and replace save package definitions in Calculation Manager only. They do not automatically validate and deploy the calculation script. Validation and deployment are separate operations, as summarized below.
Table 3-277 Calculation Manager package lifecycle
| Operation | Calculation Manager effect | Planning effect |
|---|---|---|
| Create package | Import a new primary artifact into Calculation Manager; fail if it already exists. | No deployment. |
| Replace package | Import updated package definitions for an existing primary artifact. | No deployment. |
| Validate existing package or Validate package payload with VALIDATE_ONLY | Validate without package import. | No deployment. |
| Validate existing package or Validate package payload with VALIDATE_AND_DEPLOY | On overall validation success, import/upsert the package definitions. | Deploy after import. |
| Deploy existing package | Read the saved package definitions for deployment. | Deploy and return artifact references. |
VALIDATE_ONLY validates without importing or deploying the package.
VALIDATE_AND_DEPLOY proceeds only when the overall validation result is
success; a warning or error does not satisfy that gate. On success,
it imports or updates definitions in Calculation Manager and then deploys them to Planning.
Payload validation with VALIDATE_AND_DEPLOY can therefore create or
update artifacts. It is not a preview-only operation. Existing-artifact validation uses
the retrieved package, whereas payload validation uses the submitted package.
Deploy reads the saved package from Calculation Manager; it does not accept a replacement
package body. Neither validation nor deployment launches the business rule. To execute
a rule or ruleset, use POST /HyperionPlanning/rest/v3/applications/{application}/jobs;
see Execute a Job.
Required Roles
Service Administrator
REST Resource
POST /HyperionPlanning/rest/v3/applications/{application}/calcmanager/rulesets/validate
Package type constraints
Ruleset package operations use primaryArtifact.type set to
RULESET. Include a definition in rulesets whose name
matches primaryArtifact.name. The package can include rule and ruleset
definitions; those included definitions do not change the primary artifact type.
Nested ruleset steps
A RULE step can reference an included rule or an existing accessible rule in the specified
targetPlanType. A RULESET step must reference a definition present in
this package's rulesets array, even if a ruleset of that name already
exists in Calculation Manager. Include the definitions for further nested rulesets too.
Step sequence values determine order within each containing ruleset.
Use distinct values within that ruleset. A nested ruleset defines the order of its own
steps independently.
The package example uses Plan Allocation as the primary ruleset. Its first step references
Allocation Steps, whose definition is included and calls the included Calc Step rule.
The second primary step references Existing Allocation Rule in Plan1; that rule must
already exist and be accessible, and its definition is intentionally not included.
RULE steps supply targetPlanType; the RULESET step omits it.
This is an illustrative package.
Runtime-prompt values and precedence
Existing-artifact validation accepts an optional rtps object whose
keys are variable names and whose values are strings. TargetVersion is an example
variable name, not a fixed API parameter. If both rtps and its legacy
variables alias are supplied, use the entire rtps map;
do not merge values from the legacy map.
The existing-artifact RTP-map path applies values to CALCSCRIPT variable references. It does not provide Groovy prompt-value application through that path.
Payload validation accepts the package directly, without an rtps
wrapper. Supply values on rule or ruleset variable references:
overrideValue is a reference-specific override string, and
validationValue is an explicit validation-substitution string.
A nonempty validationValue is preferred over
overrideValue for validation substitution. Referenced variable names
must be defined in the package.
The corresponding Create package example defines TargetVersion and its rule reference. Use the same artifact and variable here. The Version dimension and Working and Final members must exist; Working is used for validation in this example.
Package import and replacement scope
Package imports identify one primary artifact through primaryArtifact.
A ruleset package can also contain rules and nested rulesets. The import processes the
included definitions in variables, rules, and
rulesets; the primary-artifact designation does not limit the import
to that artifact alone.
VALIDATE_ONLY does not import package definitions. With VALIDATE_AND_DEPLOY, successful validation is followed by importing or updating the package definitions and deploying them. This import includes the definitions in the selected package, rather than only its primary artifact.
Before preparing a replacement, retrieve the current package using Get package and preserve the definitions and settings you intend to keep. Do not infer deletion of an artifact from its omission or assume that changes across all included artifacts form one atomic transaction.
Create and replace return a reference to the primary artifact. Successful ruleset deployment can return references for the primary ruleset and the included nested rulesets and rules. Inspect the returned deployment artifacts rather than assuming there is only one reference.
Package content conditions
Examples supply array properties explicitly and use [] for empty lists.
Primary rule examples also supply primaryArtifact.planType explicitly.
These example choices make the intended package clear; inclusion in an example alone
does not establish an unconditional validation requirement.
Table 3-278 Package content conditions
| Area | Condition |
|---|---|
| Primary artifact | A primary rule or ruleset must resolve to a definition in the package. Use RULE for rule endpoints and RULESET for ruleset endpoints. |
| Rule package | Include exactly one rule definition and no ruleset definitions. The examples identify the primary rule explicitly by name and planType. |
| Ruleset package | Include the primary ruleset and all referenced nested RULESET definitions. RULE steps may reference included or existing accessible rules. |
| mergeVariables | Supply this required boolean on each ruleset definition. |
| MEMBER / MEMBERS variables | Supply the dimension information needed by the selected dimension input mode. |
| Coordinate variables | Supply coordinate prompts for coordinate-based types such as CELL_REFERENCE and MEMBER_RANGE. |
| Limits | LIST needs values; EXPRESSION needs expression; SMARTLIST needs smartListName; MINMAX needs at least one nonempty min/max bound. |
| RULE steps | Supply targetPlanType. Omit it for RULESET steps. |
Plan-type identifiers
Use the application's plan-type name for planType, for example
Plan1. The examples assume HP1 contains that plan type. Substitute the
corresponding plan-type name from your application. A display name or a different
Essbase cube name is not an interchangeable identifier for these operations.
Rule List, Get, Deploy, and existing-artifact Validate operations require the
planType query parameter. Rule deletion has a conditional requirement:
supply it when deleting an undeployed rule by name from Calculation Manager.
Package bodies identify rule locations through rules[].planType,
applicable variable-scope fields, and RULE-step targetPlanType.
Examples identify a primary rule explicitly with primaryArtifact.planType.
PUT selects the rule location from the package body; do not add a
planType query parameter to a Replace request.
Ruleset resource methods do not expose the same planType query
parameter as rule methods. Rule definitions and RULE steps included inside a ruleset
package still carry their own plan-type names.
Request
For package field definitions, types, values, and content conditions, see Package variables and references and Nonempty variable and reference examples in this topic. Follow this operation's own request-body requirements.
Use HTTP Basic authentication. Send a required JSON request body with Content-Type: application/json.
Table 3-279 Request Parameters
| Name | Description | Location | JSON Type | Required | Default |
|---|---|---|---|---|---|
application
|
The name of the application. | Path | string | Yes | None |
mode
|
VALIDATE_ONLY validates; VALIDATE_AND_DEPLOY deploys only after successful validation. | Query | string | No | VALIDATE_ONLY |
primaryArtifact
|
Identifies the package primary artifact by endpoint-specific type and name, with an explicit planType in the primary-rule examples. | Request body | object | Yes | None |
primaryArtifact.type
|
Required value: RULESET. This endpoint accepts a ruleset package. | Request body | string | Yes | None |
primaryArtifact.name
|
The primary ruleset name. It must identify a matching definition in rulesets. | Request body | string | Yes | None |
variables
|
Variable definitions. Define every variable referenced by the package. Examples include this array explicitly, using [] when empty. | Request body | array | Explicit in examples | None |
rules
|
Rule definitions included with the ruleset package; the primary artifact remains a ruleset. | Request body | array | Yes | None |
rules[].name
|
The name of the rule. | Request body | string | Yes | None |
rules[].planType
|
The application plan-type name containing the rule, such as Plan1. | Request body | string | Yes | None |
rules[].script
|
Script object containing language and source. Use CALCSCRIPT or GROOVY for language. | Request body | object | Yes | None |
rules[].script.language
|
The script language: CALCSCRIPT or GROOVY. | Request body | string | Yes | None |
rules[].script.source
|
The script text for the rule. | Request body | string | Yes | None |
rules[].variableReferences
|
Runtime-prompt references for the rule. Examples include this array explicitly, using [] when there are no references. | Request body | array | Explicit in examples | None |
rulesets
|
Include the primary ruleset and every referenced nested RULESET definition. | Request body | array | Conditional; see description | None |
rulesets[].name
|
The name of the ruleset. | Request body | string | Yes | None |
rulesets[].mergeVariables
|
true merges common runtime-prompt variables across ruleset steps; false keeps step-specific references separate. | Request body | boolean | Yes | None |
rulesets[].steps
|
Ordered execution steps for this ruleset. Examples include an explicit array; each supplied step must satisfy its type-specific conditions. | Request body | array | Explicit in examples | None |
rulesets[].steps[].sequence
|
The execution order within the containing ruleset. Use distinct sequence values for its steps; nested rulesets have their own step sequences. | Request body | integer | Yes | None |
rulesets[].steps[].type
|
The artifact type executed by the step: RULE or RULESET. | Request body | string | Yes | None |
rulesets[].steps[].targetName
|
For RULE, the name of an included rule or an existing accessible rule. For RULESET, the name of a ruleset definition included in this package; an existing remote ruleset alone is insufficient. | Request body | string | Yes | None |
rulesets[].steps[].targetPlanType
|
Required for RULE steps. Omit for RULESET steps. | Request body | string | Conditional | None |
rulesets[].variableReferences
|
Runtime-prompt references targeting rules through stepPath. Examples include this array explicitly, using [] when there are no references. | Request body | array | Explicit in examples | None |
Supply the package directly. Provide any runtime-prompt values through validationValue or overrideValue on variable references.
RULE steps may reference a rule included in the package or an existing accessible rule.
Supply targetPlanType for RULE steps. Include every nested RULESET
definition in rulesets and omit targetPlanType for
RULESET steps.
Example request body:
{
"primaryArtifact": {
"type": "RULESET",
"name": "Plan Allocation"
},
"variables": [
{
"name": "TargetVersion",
"scope": {
"level": "APPLICATION"
},
"dataType": "MEMBER",
"promptText": "Select target version",
"defaultValue": "Working",
"dimension": "Version",
"dimensionInputMode": "NAME",
"limits": {
"kind": "LIST",
"values": [
"Working",
"Final"
]
}
}
],
"rules": [
{
"name": "Calc Step",
"planType": "Plan1",
"script": {
"language": "CALCSCRIPT",
"source": "SET UPDATECALC OFF;"
},
"variableReferences": [
{
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
}
],
"rulesets": [
{
"name": "Plan Allocation",
"mergeVariables": true,
"steps": [
{
"sequence": 1,
"type": "RULESET",
"targetName": "Allocation Steps"
},
{
"sequence": 2,
"type": "RULE",
"targetName": "Existing Allocation Rule",
"targetPlanType": "Plan1"
}
],
"variableReferences": [
{
"stepPath": [
1,
1
],
"ruleName": "Calc Step",
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
},
{
"name": "Allocation Steps",
"mergeVariables": true,
"steps": [
{
"sequence": 1,
"type": "RULE",
"targetName": "Calc Step",
"targetPlanType": "Plan1"
}
],
"variableReferences": []
}
]
}
Example URL
https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rulesets/validate?mode=VALIDATE_ONLY
Response
Success: 200 OK. The response body contains the operation result.
For completed validation, inspect the JSON status,
deployed, and per-rule diagnostics. HTTP 200 alone does not establish
validation success. Validation results are separate from HTTP request failures.
A completed validation returns HTTP 200 even when the result body reports
status:"error". HTTP success means that the validation request completed;
it does not mean that the script passed validation or that artifacts were deployed.
Always inspect status, deployed, and the per-rule
diagnostics.
For VALIDATE_AND_DEPLOY, deployment proceeds only when the overall
status is success. Neither warning
nor error satisfies this gate. VALIDATE_ONLY does not
deploy even when validation succeeds.
A malformed request, authentication/access failure, or transport/service failure is a separate HTTP error outcome. Do not interpret such errors as completed script-validation results or assume they contain the validation-result structure shown here.
Supported Media Types: application/json
Table 3-280 Response Parameters
| Name | Description |
|---|---|
mode
|
The validation mode used for the operation. |
status
|
String. Overall validation result, commonly success, warning, or error. Only success permits VALIDATE_AND_DEPLOY to proceed. |
deployed
|
Indicates whether artifacts were deployed to Planning. |
rules
|
The validation results for the rules. |
rules[].name
|
The name of the rule. |
rules[].application
|
The application containing the rule. |
rules[].planType
|
The application plan-type name containing the rule, such as Plan1. |
rules[].status
|
String. The individual rule validation result, commonly success, warning, or error; may be null or omitted. Inspect it together with the overall status and diagnostics. |
rules[].unresolvedRtpNames |
String containing unresolved runtime-prompt names. This is not defined as a JSON array; it may be null or omitted. |
rules[].errors |
Array of diagnostic objects; may be null or omitted when no details are available. |
rules[].errors[].message |
String containing a diagnostic message. |
rules[].errors[].lineNumber |
Optional integer identifying the reported script line; may be null or omitted. |
Sample Response
{
"mode": "VALIDATE_ONLY",
"status": "success",
"deployed": false,
"rules": [
{
"name": "Calc Step",
"application": "HP1",
"planType": "Plan1",
"status": "success"
}
]
}
Package variables and references
This embedded reference describes the package structure shared by the Calculation Manager artifact operations. It does not change an operation's request-body requirements: create, replace, and payload validation accept package bodies; existing-artifact validation uses its documented prompt-value body, and GET, list, delete, and deploy do not accept a replacement package just because this reference is included.
Table 3-281 Package structure
| Property | JSON Type | Description and conditions |
|---|---|---|
primaryArtifact |
object | Primary type/name and rule plan type. RULE endpoints require RULE and exactly one rule definition, with no ruleset definitions. RULESET endpoints require RULESET and its matching definition in rulesets. |
variables |
array of objects | Variable definitions available to references in this package. Define every referenced variable in this array. |
rules |
array of objects | Rule definitions with name, planType, script, optional displayLabel/executionOptions, and variableReferences. |
rulesets |
array of objects | Ruleset definitions with name, mergeVariables, steps, and variableReferences. Include every nested RULESET definition. |
links |
array of objects | Response links where populated; not a writable package property. |
Table 3-282 Variable definition: variables[]
| Property | JSON Type | Description and conditions |
|---|---|---|
name |
string | Required variable name. Duplicate variable names in the package are rejected. |
scope |
object | Required scope descriptor; see the scope table. |
dataType |
string | Required. Supported values are listed below. |
promptText |
string | Optional text displayed for the runtime prompt. |
defaultValue |
string | Optional runtime-prompt default value, represented as a string. |
useLastValue |
boolean | Optional preference to reuse the last value where supported. |
allowMissing |
boolean | Optional missing-value setting for the variable. |
dimension |
string | Dimension name for dimension-dependent prompts. MEMBER/MEMBERS require dimension information. |
dimensionType |
string | Dimension-type identifier when using dimension-type-based input; do not substitute an arbitrary label. |
dimensionInputMode |
string | NAME or TYPE. Use the dimension name for NAME and corresponding dimension-type information for TYPE. |
dynamicMemberParent |
string | Optional parent setting for dynamic-member prompts where applicable. |
limits |
object | Optional tagged limit object: LIST, EXPRESSION, SMARTLIST, or MINMAX. |
coordinates |
array of objects | Coordinate prompt entries for coordinate-based types such as CELL_REFERENCE and MEMBER_RANGE; see coordinate fields below. |
Supported data types: STRING, STRING_AS_NUMBER,
INTEGER, NUMERIC, REAL,
PERCENT, DATE_AS_NUMBER, DIMENSION,
MEMBER, MEMBERS, CELL_REFERENCE,
MEMBER_RANGE, and SMARTLIST.
Table 3-283 Variable scope: variables[].scope
| Property | JSON Type | Description and conditions |
|---|---|---|
level |
string | Required: APPLICATION, PLAN_TYPE, RULE, or RULESET. |
planType |
string | Supply the application plan-type name for PLAN_TYPE and RULE scopes, such as Plan1. |
ruleName |
string | Required targeting information for RULE scope; identifies the rule together with planType. |
Table 3-284 Variable limits: variables[].limits
| Property | JSON Type | Description and conditions |
|---|---|---|
kind |
string | Required discriminator: LIST, EXPRESSION, SMARTLIST, or MINMAX. |
values |
array of strings | Required for LIST. Example: {"kind":"LIST","values":["Working","Final"]}. |
expression |
string | Required for EXPRESSION. Holds the permitted-value expression. |
smartListName |
string | Required for SMARTLIST; name of the applicable existing Smart List. |
min / max |
string | MINMAX bounds. Supply at least one nonempty bound. Example: {"kind":"MINMAX","min":"0","max":"100"}. |
Table 3-285 Coordinate prompt: variables[].coordinates[]
| Property | JSON Type | Description and conditions |
|---|---|---|
dimension |
string | Required dimension for this coordinate prompt. |
promptText |
string | Optional prompt text for this coordinate. |
defaultExpression |
string | Optional default member-selection expression for this coordinate. |
Table 3-286 Rule definition: rules[]
| Property | JSON Type | Description and conditions |
|---|---|---|
name / planType |
string | Rule name and application plan-type name, such as Plan1. |
displayLabel |
string | Optional rule display label. |
script.language |
string | CALCSCRIPT or GROOVY. |
script.source |
string | Script text. |
executionOptions |
object | Optional enablePreProcessing, enablePostProcessing, enableNotifications, and disabled boolean flags. |
variableReferences |
array of objects | Ordered runtime-prompt references using the fields above. |
Table 3-287 Rule variable reference: rules[].variableReferences[]
| Property | JSON Type | Description and conditions |
|---|---|---|
sequence |
integer | Required positive reference sequence. Rule-reference sequence values must be distinct within that rule. |
variableName |
string | Required; must resolve to a definition in the package variables array. |
hidden |
boolean | Optional setting that hides the runtime prompt. |
useAsOverrideValue |
boolean | Optional flag identifying use of an override value for this reference. |
overrideValue |
string | Optional reference-specific override value. |
validationValue |
string | Optional value for validation substitution. A nonempty validationValue is preferred over overrideValue for validation. |
allowMissing |
boolean | Optional missing-value setting at the reference level. |
Table 3-288 Ruleset definition: rulesets[]
| Property | JSON Type | Description and conditions |
|---|---|---|
name |
string | Ruleset name; primaryArtifact.name identifies the primary ruleset. |
mergeVariables |
boolean | Required setting. true merges common runtime-prompt variables across rule steps; false keeps step-specific prompt references separate. Use rule and step-path targeting for reference-specific values. |
steps |
array of objects | Ordered steps with positive sequence, type, targetName, and targetPlanType for RULE. RULESET steps omit targetPlanType and require an included nested ruleset definition. |
variableReferences |
array of objects | References targeting rule prompts through stepPath, ruleName, sequence, and variableName. |
Table 3-289 Ruleset variable reference: rulesets[].variableReferences[]
| Property | JSON Type | Description and conditions |
|---|---|---|
stepPath |
array of integers | Required nonempty sequence path to the referenced rule step. Values are positive step sequence numbers, not zero-based array indexes. For nested steps, [1,1] follows sequence 1 in the parent and then sequence 1 in the child. |
ruleName |
string | Required rule name resolved by stepPath. Rule-name matching is case-insensitive. |
sequence |
integer | Required positive variable-reference sequence for the target rule. |
variableName |
string | Required variable name defined in this package. |
hidden / useAsOverrideValue / allowMissing |
boolean | Optional reference flags, as for rule variable references. |
overrideValue / validationValue |
string | Optional reference-specific values, as for rule variable references. |
Referenced variable names must resolve within the package. Duplicate names and duplicate reference sequences in the same rule are rejected. Ruleset references must identify valid step paths and rule names; duplicate references for the same step path and variable sequence are rejected. Steps in each ruleset also require distinct sequence values.
Nonempty variable and reference examples
These illustrative packages assume Plan1 and the Version members Working and Final exist. The minimal script isolates variable/reference authoring; it does not demonstrate consuming the prompt in a calculation.
A rule package with one application-scoped member variable and its matching rule reference:
{
"primaryArtifact": {
"type": "RULE",
"name": "Allocate Plan Targets",
"planType": "Plan1"
},
"variables": [
{
"name": "TargetVersion",
"scope": {
"level": "APPLICATION"
},
"dataType": "MEMBER",
"promptText": "Select target version",
"defaultValue": "Working",
"dimension": "Version",
"dimensionInputMode": "NAME",
"limits": {
"kind": "LIST",
"values": [
"Working",
"Final"
]
}
}
],
"rules": [
{
"name": "Allocate Plan Targets",
"planType": "Plan1",
"script": {
"language": "CALCSCRIPT",
"source": "SET UPDATECALC OFF;"
},
"variableReferences": [
{
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
}
],
"rulesets": []
}
A nested ruleset package with the same variable. The ruleset reference uses
stepPath:[1,1] to reach Calc Step through Allocation Steps, and
sequence:1 to identify the variable reference in that rule.
{
"primaryArtifact": {
"type": "RULESET",
"name": "Plan Allocation"
},
"variables": [
{
"name": "TargetVersion",
"scope": {
"level": "APPLICATION"
},
"dataType": "MEMBER",
"promptText": "Select target version",
"defaultValue": "Working",
"dimension": "Version",
"dimensionInputMode": "NAME",
"limits": {
"kind": "LIST",
"values": [
"Working",
"Final"
]
}
}
],
"rules": [
{
"name": "Calc Step",
"planType": "Plan1",
"script": {
"language": "CALCSCRIPT",
"source": "SET UPDATECALC OFF;"
},
"variableReferences": [
{
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
}
],
"rulesets": [
{
"name": "Plan Allocation",
"mergeVariables": false,
"steps": [
{
"sequence": 1,
"type": "RULESET",
"targetName": "Allocation Steps"
}
],
"variableReferences": [
{
"stepPath": [
1,
1
],
"ruleName": "Calc Step",
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
},
{
"name": "Allocation Steps",
"mergeVariables": false,
"steps": [
{
"sequence": 1,
"type": "RULE",
"targetName": "Calc Step",
"targetPlanType": "Plan1"
}
],
"variableReferences": []
}
]
}
Both examples show separate default, override, and validation values. Working is the variable default and the explicit validation value; Final is the reference override. The nonempty validation value takes precedence for validation substitution.
HTTP errors
For common HTTP status definitions, see Error Handling and Status Codes. Inspect the actual response status and diagnostic details when handling a failed request.
Table 3-290 HTTP error cases
| HTTP status | Condition | Action |
|---|---|---|
| 400 Bad Request | Malformed or invalid package payload, including missing or invalid package fields. | Correct the request using the operation-specific package conditions. |
| 400 Bad Request | Invalid validation mode or request parameters. | Use VALIDATE_ONLY or VALIDATE_AND_DEPLOY and supply the required artifact location. |
| 401 Unauthorized | Authentication credentials are missing or invalid. | Authenticate using a supported method. |
| 403 Forbidden | The explicit administrator gate rejects the user. | Use a session with the required administrator role. |
| 500 Internal Server Error | An unexpected server condition, when reported with this status. | Inspect the error details and the resulting artifact state before deciding whether to retry. |
Service or transport failures must be handled separately from completed validation results. A successful HTTP response from a validation operation can still report a script-validation error in its JSON body.
Variable settings and field examples
The following examples illustrate scope, limit, coordinate, and option shapes. Referenced artifacts, dimensions, members, and Smart Lists must exist in the target application. Example values do not imply defaults for omitted properties.
Table 3-291 Variable scope examples
| Property or object | Example | Meaning and conditions |
|---|---|---|
APPLICATION scope |
{"level":"APPLICATION"} |
Application-scoped variable. |
PLAN_TYPE scope |
{"level":"PLAN_TYPE","planType":"Plan1"} |
Variable associated with the specified plan-type location. |
RULE scope |
{"level":"RULE","planType":"Plan1","ruleName":"Allocate Plan Targets"} |
Rule-scoped variable; identifies the rule by name and plan-type location. |
Table 3-292 Limits and coordinate examples
| Property or object | Example | Meaning and conditions |
|---|---|---|
LIST limits |
{"kind":"LIST","values":["Working","Final"]} |
A list of permitted string values. Use members that exist when the variable is member-valued. |
EXPRESSION limits |
{"kind":"EXPRESSION","expression":"ILvl0Descendants(Version)"} |
An expression determining the permitted selections; applicable dimensions and members must exist. |
SMARTLIST limits |
{"kind":"SMARTLIST","smartListName":"Planning Status"} |
Identifies an existing Smart List. This example uses only kind and smartListName. |
MINMAX limits |
{"kind":"MINMAX","min":"0","max":"100"} |
Bounds are JSON strings; supply at least one nonempty bound. |
Coordinate prompt |
{"dimension":"Version","promptText":"Select version","defaultExpression":"Working"} |
A coordinate entry contains its dimension and optional prompt/default expression. Place entries inside the variable coordinates array. |
Table 3-293 Prompt flags and value precedence
| Property or object | Example | Meaning and conditions |
|---|---|---|
useLastValue |
true |
Use the last supplied prompt value where this option applies. |
allowMissing |
false |
Missing-value allowance at the variable or reference level where supplied. |
hidden |
true |
Hide this variable reference from runtime prompting. |
useAsOverrideValue |
true |
Mark the reference to use its supplied override value. |
overrideValue |
"Final" |
Reference-specific value override. |
validationValue |
"Working" |
Value used for validation substitution; a nonempty value is preferred over overrideValue for validation. |
mergeVariables |
false |
Keep step-specific prompt references separate. true merges common prompt variables across ruleset steps. |
Table 3-294 Rule executionOptions fields
| Property or object | Example | Meaning and conditions |
|---|---|---|
enablePreProcessing |
true |
Enable the rule pre-processing option. |
enablePostProcessing |
true |
Enable the rule post-processing option. |
enableNotifications |
true |
Enable the rule notification option. |
disabled |
false |
Set the rule disabled option. These values configure the rule; they do not launch it. |
Supply a limit object matching its kind. Member variables require
dimension information, coordinate-based variables require coordinate entries, and
reference values must match the variable's supported data type and limits. Rule and
ruleset references must resolve to variables defined in the package.
Package examples and lifecycle
These independent examples assume application HP1 has the BSO plan type Plan1, the Version dimension with stored Working and Final members, the Account dimension, and the members Actual, No Entity, P_TP, USD, FY16, and Jan on their corresponding axes. The members must exist and be accessible. The Groovy example requires Groovy business-rule support.
Create examples require new primary artifact names. Replace examples require an existing primary artifact. Adapt member selections and calculation scope to your application.
Minimal rule package:
{
"primaryArtifact": {
"type": "RULE",
"name": "Minimal Rule",
"planType": "Plan1"
},
"variables": [],
"rules": [
{
"name": "Minimal Rule",
"planType": "Plan1",
"script": {
"language": "CALCSCRIPT",
"source": "SET UPDATECALC OFF;"
},
"variableReferences": []
}
],
"rulesets": []
}
CALCSCRIPT package with a TargetVersion runtime prompt. The calculation fixes on that version and the listed member selections, then calculates the Account dimension.
{
"primaryArtifact": {
"type": "RULE",
"name": "Allocate Plan Targets",
"planType": "Plan1"
},
"variables": [
{
"name": "TargetVersion",
"scope": {
"level": "APPLICATION"
},
"dataType": "MEMBER",
"promptText": "Select target version",
"defaultValue": "Working",
"dimension": "Version",
"dimensionInputMode": "NAME",
"limits": {
"kind": "LIST",
"values": [
"Working",
"Final"
]
}
}
],
"rules": [
{
"name": "Allocate Plan Targets",
"planType": "Plan1",
"script": {
"language": "CALCSCRIPT",
"source": "SET UPDATECALC OFF;\nFIX ({TargetVersion}, \"Actual\", \"No Entity\", \"P_TP\", \"USD\", \"FY16\", \"Jan\")\n CALC DIM (\"Account\");\nENDFIX"
},
"variableReferences": [
{
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
}
],
"rulesets": []
}
Groovy package that reads the Plan1 cube name and writes it to the rule log. It defines no runtime prompts; the existing-validation RTP-map path is not used for this example.
{
"primaryArtifact": {
"type": "RULE",
"name": "Inspect Allocation Cube",
"planType": "Plan1"
},
"variables": [],
"rules": [
{
"name": "Inspect Allocation Cube",
"planType": "Plan1",
"script": {
"language": "GROOVY",
"source": "/* RTPS: */\ndef cube = operation.application.getCube(\"Plan1\")\nprintln \"Allocation cube: ${cube.getName()}\""
},
"variableReferences": []
}
],
"rulesets": []
}
Nested ruleset package with a step-path override. Plan Allocation targets Calc Step through Allocation Steps using stepPath [1,1]. The ruleset reference supplies Final for its override and validation value, while the variable default remains Working.
{
"primaryArtifact": {
"type": "RULESET",
"name": "Plan Allocation"
},
"variables": [
{
"name": "TargetVersion",
"scope": {
"level": "APPLICATION"
},
"dataType": "MEMBER",
"promptText": "Select target version",
"defaultValue": "Working",
"dimension": "Version",
"dimensionInputMode": "NAME",
"limits": {
"kind": "LIST",
"values": [
"Working",
"Final"
]
}
}
],
"rules": [
{
"name": "Calc Step",
"planType": "Plan1",
"script": {
"language": "CALCSCRIPT",
"source": "SET UPDATECALC OFF;\nFIX ({TargetVersion}, \"Actual\", \"No Entity\", \"P_TP\", \"USD\", \"FY16\", \"Jan\")\n CALC DIM (\"Account\");\nENDFIX"
},
"variableReferences": [
{
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
}
],
"rulesets": [
{
"name": "Plan Allocation",
"mergeVariables": false,
"steps": [
{
"sequence": 1,
"type": "RULESET",
"targetName": "Allocation Steps"
}
],
"variableReferences": [
{
"stepPath": [
1,
1
],
"ruleName": "Calc Step",
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Final",
"allowMissing": false
}
]
},
{
"name": "Allocation Steps",
"mergeVariables": false,
"steps": [
{
"sequence": 1,
"type": "RULE",
"targetName": "Calc Step",
"targetPlanType": "Plan1"
}
],
"variableReferences": []
}
]
}
Table 3-295 Consistent rule-package lifecycle
| Stage | Request | Input | Result handling |
|---|---|---|---|
| Create | POST https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules |
Use the CALCSCRIPT/RTP package below. | Read the name-valued id and self link from this response. |
| GET | GET https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets?planType=Plan1 |
No request body. | Retrieve the saved package and preserve its intended definitions. |
| Validate | POST https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets/validate?mode=VALIDATE_ONLY&planType=Plan1 |
{"rtps":{"TargetVersion":"Working"}} | Inspect overall/per-rule status; no deployment in this mode. |
| Deploy | POST https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets/deploy?planType=Plan1 |
No replacement package body. | Read deployed identifiers from this operation response. |
| Replace | PUT https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets |
Use the replacement package below. | Read this response reference; the saved package changes without automatic deployment. |
| Redeploy | POST https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets/deploy?planType=Plan1 |
No replacement package body. | Read identifiers and results from this redeploy response independently. |
Use the same Allocate Plan Targets artifact and TargetVersion variable throughout the lifecycle. Obtain response identifiers from each operation. Calculation Manager-only create/replace identifiers and deployed Planning identifiers have different roles; do not carry a fabricated UUID through the sequence or infer UUID lookup support from an identifier returned as response data.
Replacement package for the PUT stage. It retains the intended variable/reference settings and adds SET AGGMISSG ON to the calculation source:
{
"primaryArtifact": {
"type": "RULE",
"name": "Allocate Plan Targets",
"planType": "Plan1"
},
"variables": [
{
"name": "TargetVersion",
"scope": {
"level": "APPLICATION"
},
"dataType": "MEMBER",
"promptText": "Select target version",
"defaultValue": "Working",
"dimension": "Version",
"dimensionInputMode": "NAME",
"limits": {
"kind": "LIST",
"values": [
"Working",
"Final"
]
}
}
],
"rules": [
{
"name": "Allocate Plan Targets",
"planType": "Plan1",
"script": {
"language": "CALCSCRIPT",
"source": "SET AGGMISSG ON;\nSET UPDATECALC OFF;\nFIX ({TargetVersion}, \"Actual\", \"No Entity\", \"P_TP\", \"USD\", \"FY16\", \"Jan\")\n CALC DIM (\"Account\");\nENDFIX"
},
"variableReferences": [
{
"sequence": 1,
"variableName": "TargetVersion",
"hidden": false,
"useAsOverrideValue": true,
"overrideValue": "Final",
"validationValue": "Working",
"allowMissing": false
}
]
}
],
"rulesets": []
}
Separate validation-failure input: use the complete rule package with its script object changed as shown below, and submit it to the payload-validation endpoint in VALIDATE_ONLY mode. The object below is a script-field fragment, not a complete request body.
POST https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/validate?mode=VALIDATE_ONLY
{
"language": "CALCSCRIPT",
"source": "NOT_A_VALID_CALC_COMMAND;"
}
Inspect the actual overall status and per-rule diagnostics. A completed validation can return HTTP 200 with an error result. This validation-only test does not replace the saved package or deploy the invalid script.
Deletion scopes are independent alternatives after the example lifecycle. Select the intended repository scope rather than running all three against the same artifact:
DELETE https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets?planType=Plan1&deleteFrom=CALC_MANAGER
DELETE https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets?planType=Plan1&deleteFrom=PLANNING
DELETE https://<BASE-URL>/HyperionPlanning/rest/v3/applications/HP1/calcmanager/rules/Allocate%20Plan%20Targets?planType=Plan1&deleteFrom=BOTH
CALC_MANAGER leaves the Planning copy in place; PLANNING leaves the Calculation Manager copy in place. BOTH deletes from Calculation Manager first and is not atomic across the repositories. A Planning ruleset reference can block rule deletion.