Import a Semantic Foundation Workbook

Validates or imports governed semantic metadata from an Excel workbook in the Planning Inbox.

Required Roles

Application administrator.

REST Resource

POST /HyperionPlanning/rest/v3/applications/{application}/semanticfoundation/workbooks/action/import

Request

Use HTTP Basic authentication. Supported Media Types: application/json.

Table 3-669 Request Parameters

Name Description Type Required Default
application Name of the application. Path Yes None
fileName Inbox basename no longer than 255 UTF-8 bytes, ending in .xlsx, and containing only letters, digits, underscores, hyphens, periods, or spaces; directory paths are not accepted. Payload Yes Not specified
mode VALIDATE changes no metadata, MERGE applies only Proposed changes that do not conflict with the Existing baseline, and REPLACE replaces the governed catalog as an explicit restore. Payload No VALIDATE
confirmReplace Must be true when mode is REPLACE. Payload For REPLACE mode Not specified

Upload the workbook to the Planning Inbox first. fileName must be an .xlsx basename of at most 255 UTF-8 bytes using letters, digits, underscores, hyphens, periods, or spaces; directory paths are not accepted.

VALIDATE changes no metadata. MERGE applies nonconflicting Proposed changes against the Existing baseline, preserves concurrent server changes and existing substitution-variable scopes, and reports conflicts. REPLACE restores the full governed catalog and requires confirmReplace: true.

Association targets must already exist; import creates no outline metadata and changes no variable values. Member targets use dimension-qualified names, including qualified shared-member names. Substitution variables resolve by logical name, preferring application scope and then the lowest available plan-type value. User variables resolve by name and validate Dimension when supplied.

Example request body:

{
  "fileName": "vision-semantic-foundation.xlsx",
  "mode": "MERGE",
  "confirmReplace": false
}

Example URL

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/Vision/semanticfoundation/workbooks/action/import

Response

Supported Media Types: application/json

MERGE imports valid rows and skips invalid rows with diagnostics. VALIDATE reports resolvable row issues without changing metadata. Conflicting edits in legacy duplicate rows preserve the association and produce a diagnostic; a single unambiguous edit overrides unchanged duplicates.

Table 3-670 Response Parameters

Name Description
fileName Planning Inbox or Outbox workbook basename.
mode Completed operation mode.
businessConceptCount Number of Business Concept rows processed.
associationCount Number of logical association rows exported or valid Proposed association rows processed.
semanticContextIntersectionCount Number of Semantic Context Intersection rows processed.
warnings Non-blocking workbook compatibility warnings.
diagnostics Row-level workbook issues reported during validation or import.
diagnostics[].sheet Workbook sheet containing the issue.
diagnostics[].row Workbook row containing the issue.
diagnostics[].code Stable identifier for the workbook issue.
diagnostics[].message Explanation of the workbook issue.

Sample Response

{
  "fileName": "vision-semantic-foundation.xlsx",
  "mode": "MERGE",
  "businessConceptCount": 24,
  "associationCount": 58,
  "semanticContextIntersectionCount": 6,
  "warnings": [],
  "diagnostics": [
    {
      "sheet": "Associations",
      "row": 4,
      "code": "UNRESOLVED_ASSOCIATION",
      "message": "Association references an unavailable object."
    }
  ]
}