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."
}
]
}