Find Forms by Member Slices

Finds readable forms that structurally cover every required correlated member slice.

Required Roles

Application Administrator

REST Resource

POST /HyperionPlanning/rest/v3/applications/{application}/semanticfoundation/forms/action/findbyslices

Request

Table 3-663 Parameters

Name Description Type Required Default
application Name of the application. Path Yes None
requiredSlices One or more correlated required intersections. Payload Yes Not specified
requiredSlices[].dimensions Dimension-member selections in the intersection. Payload Yes Not specified
requiredSlices[].dimensions.Years Year members required together with the other selections in this slice. Payload No Not specified
requiredSlices[].dimensions.Account Account members required together with the other selections in this slice. Payload No Not specified
requiredSlices[].dimensions.Entity Entity members required together with the other selections in this slice. Payload No Not specified
preferredSlices Optional correlated soft intersections used only to rank confirmed matches. Payload No Not specified
preferredSlices[].dimensions Dimension-member selections in the intersection. Payload Yes Not specified
preferredSlices[].dimensions.Entity Entity members used to rank confirmed matches. Payload No Not specified
candidateFormNames Optional form-name scope. Payload No Not specified
includeDiagnostics When true, returns readable-form diagnostics for no-match and indeterminate results; false returns only confirmed matches and summary counts. Payload No False
headerPreviewLimit Optional maximum runtime row and column header tuples per confirmed caller-readable structural match. Payload No 0
headerPreviewFormLimit Maximum confirmed caller-readable structural matches for which a bounded runtime header preview is materialized. Payload No 10

A required slice is a correlated intersection: its dimensions must occur together. Every required slice must be covered. Preferred slices rank matches without excluding required matches.

The service filters requested members by caller security and silently omits unreadable candidate forms. Set includeDiagnostics to true for no-match and indeterminate diagnostics. Header preview limits are 0–100 tuples and 0–50 forms; zero tuples omits previews.

Example request body:

{
  "requiredSlices": [
    {
      "dimensions": {
        "Years": [
          "FY25"
        ],
        "Account": [
          "Sales"
        ],
        "Entity": [
          "USA"
        ]
      }
    }
  ],
  "preferredSlices": [
    {
      "dimensions": {
        "Entity": [
          "USA"
        ]
      }
    }
  ],
  "candidateFormNames": [
    "Expense by Group"
  ],
  "includeDiagnostics": false,
  "headerPreviewLimit": 0,
  "headerPreviewFormLimit": 10
}

Example URL

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/Vision/semanticfoundation/forms/action/findbyslices

Response

Supported Media Types: application/json

A structural match does not guarantee runtime access to fixed form members outside the requested slice. Optional header previews contain headers, not data cells or form definition selections.

Table 3-664 Response Parameters

Name Description
matches Readable forms that structurally cover all required slices.
matches[].formName Readable form name.
matches[].outcome Result of structurally evaluating the caller's security-filtered required slices against a caller-readable form.
matches[].determinedBy Evidence source that conclusively established the match.
matches[].preferenceScore Number of preferred slices structurally covered by this confirmed caller-readable match.
summary Counts of readable candidate forms by evaluation outcome.
summary.candidateForms Number of distinct readable forms evaluated.
summary.matchedForms Number of confirmed caller-readable structural matches.
summary.noMatchForms Number of forms conclusively determined not to cover the required slices for the caller.
summary.indeterminateForms Number of forms that could not be classified safely.

Sample Response

{
  "matches": [
    {
      "formName": "Expense by Group",
      "outcome": "MATCH",
      "determinedBy": "STATIC",
      "preferenceScore": 1
    }
  ],
  "summary": {
    "candidateForms": 1,
    "matchedForms": 1,
    "noMatchForms": 0,
    "indeterminateForms": 0
  }
}