Skip to main content
Documentation
Documentation
Adaptive Planning
Last Updated: 2023-06-23
Cube Sheet Definition

Cube Sheet Definition

URL Endpoint

HTTPS://api.adaptiveplanning.com/api/rest/modeling/<version>/<tenant>/sheet/cube/definition
Version: v1
Category
Data submission
Description
Metadata Modification
Permissions Required to Invoke
Model Management
Model includes: sheets, accounts, dimensions, and formulas
Parameters Required on Request
name

Supported HTTP VERB(s)

HTTP Verb
Single Resource
Description
PATCH
Supported
Insert or Update a cube sheet definition
DELETE
Supported
Delete a cube sheet definition
OPTIONS
Supported
Returns the list of HTTP verbs supported for this collection resource.

PATCH

Request URI
/sheet/cube/definition
Update the cube sheet definition matching the provided query parameter.
If a sheet with the matching name does not exist, a new cube sheet will be created with the given properties.
Sample Request by Name
https://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/cube/definition?name=Sales Cube
Sample Request Header
Accept-Language: en
Sample Request Body
See Request Body section
Query Parameters
Name
Description
Required
instanceCode
The instanceCode to retrieve values from. For example, GLOBO. If no instanceCode is specified, the default instance of the user is used.
N
name
The name of the sheet.
N
reorderColumns
Setting this query parameter to true will change the order of the column list to reflect the ordering of columns given in the api request body. By default this is set to false. See Reference: Re-ordering Columns for Modeled and Cube Sheet Definition JSON APIs.
N
Request Body
Sample Request Body
The same cube sheet definition format is used as the JSON payload for both endpoints.
Request Format
 
{
   "properties": {
       "description": "Expense Cube",
       "prefix": "Expense",
       "horizontalAxis": {
           "type": "level"
       },
       "verticalAxis": [
           {
               "type": "account"
           },
           {
               "type": "dimension",
               "name": "ProductFurniture"
           }
       ]
   },
   "columns": [
       {
           "properties": {
               "name": "Base Pay",
               "type": "dimension"
           },
           "availability":List<SheetAvaliabilityDTO>,
           "defaultAvailability": false
       }
   ],
   "accounts": [
       {
           "name": "AccountName",
           "code": "AccountCode"
       }
   ],
   "accessibility": {
       "usernames": [ "test@greenco.com" ],
       "excludedFromWorkflow": true
   }
}
Example Request:
Example Request for Sheet Creation
 
{
   "properties": {
       "description": "Test description",
       "prefix": "TestPrefix",
       "horizontalAxis": {
           "type": "level"
       },
       "verticalAxis": [
           {
               "type": "account"
           },
           {
               "type": "dimension",
               "name": "Base Pay"
           }
       ]
   },
   "columns": [
       {
           "properties": {
               "type": "Account"
           },
           "defaultAvailability": true
       },
       {
           "properties": {
               "type": "Level"
           },
           "defaultAvailability": true
       },
       {
           "properties": {
               "type": "Time"
           }
       },
       {
           "properties": {
               "name": "Base Pay",
               "type": "dimension"
           },
           "defaultAvailability": true
       }
   ],
   "accounts": [
       {
           "name": "AccountName",
           "code": "AccountCode",
           "type": "Standard"
       }
   ]
}
Sheet definition object
Name
Description
Required
properties
Object containing general sheet properties
N
columns
List of cube sheet column objects.
N
accounts
List of account objects
N
accessibility
Object containing defining user-assigned sheet accessibility.
N
Sheet properties object
Name
Description
Required
Type
Default
description
Sheet description.
N
string
Empty string
prefix
Sheet prefix used for the account code.
N
string
userAssigned
Whether the sheet is a user-assigned sheet or (by default) a level-assigned sheet.
N
boolean
false
timeStratumCode
The time stratum code associated with the data in the sheet.
N
string
GL Time Stratum
recalculateOnDemand
Whether recalculate on demand is enabled for the sheet.
N
boolean
false
rearrangeGLAndCustomAccounts
Whether users are allowed to rearrange cube-entered accounts with other cube accounts. This can only be enabled when cube standard accounts exist or are being created in the request.
N
boolean
false
hideRollupTotals
Whether to hide rollup totals to improve sheet performance.
N
boolean
false
horizontalAxis
Column reference object identifying the column on the horizontal axis.
N
column object
Time
verticalAxis
List of column reference objects identifying the columns on the vertical axis. If provided, the vertical axis will overwrite any previous selections.
N
column object array
Account
maxColumnWidth
Them maximum width in pixels for each column. Should be between 10 and 1000, or 0 if not width is specified.
N
integer
0
suppressZeroRows
Whether zero rows are suppressed.
N
boolean
false
Sheet column reference object
Name
Description
Required
Name
Column name. Required for custom dimension and attributes.
Y
type
Column type.
Y
Sheet column object
Name
Description
Required
properties
Object containing sheet column properties.
Y
availability
List of sheet availability objects for the current column. See Sheet Availability for details on the list format.
N
defaultAvailability
The default availability to apply to all values, unless otherwise specified in availability. Valid for level and dimension columns.
N
delete
Request to delete column from the given sheet. Not valid for columns that are dependent on existing columns that are not flagged for deletion (such as dimension attributes).
N
Sheet columns properties object
Name
Description
Required
Type
Default
name
Column name. For custom dimension and attribute columns, the name will match the name of the respective custom dimension or attribute.
Y
string
type
The type of column.
Possible values: LEVEL, ACCOUNT, TIME, DIMENSION, LEVEL_ATTRIBUTE, ACCOUNT_ATTRIBUTE, DIMENSION_ATTRIBUTE
Y
string
initialBalance
Whether the initial balance will be visible on the sheet. Only valid for time columns.
N
boolean
true
visibleTimeStratumCodes
Defines the list of visible time stratum on the sheet. Only valid for time columns.
N
string array
All time stratum
editableOnSheet
Whether new values can be added to the dimension column from the sheet. Only valid for dimension and text selector columns.
N
boolean
false
newValueBehavior
Defines whether to enable or disable new values when the are added to the underlying dimension. Only valid for dimension columns. Supported values: AVAILABLE, UNAVAILABLE, or PARENT
N
string
AVAILABLE
Sheet column lookup table object
Name
Description
Required
Type
Default
name
Lookup table name.
Y
string
displayAs
The Display As format for this lookup table. Possible values: NUMBER and PERCENT. Only valid for value lookup tables.
N
string
NUMBER
decimalPrecision
The decimal precision for values in this lookup table. Possible values: 0 to 9.
N
integer
0
type
The type of lookup table. Possible values: VALUE, SPREAD.
Y
string
Sheet account object
Name
Description
Required
name
The account name.
Y
code
The account code.
Y
parent
The parent account.
N
Type
The account type.
Y
description
The account description.
N
shortName
The account short name.
N
isCumulative
Returns whether the account is cumulative.
N
isPlanByDelta
Returns whether the account is plan by delta.
N
isActualsByDelta
Returns whether the acount is actuals by delta.
N
isLink
Returns whether the account is a linked account or not.
N
timeRollupType
The type of rollup to perform for time rollups.
N
timeWeightAccount
The weight account used for time rollups.
N
levelDimRollupType
The type of rollup to perform for level/custom dimension rollups.
N
levelDimWeightAccount
The weight account used for leve/custom dimension rollups.
N
levelDimRollupText
The rollup text vlaue used in level/custom dimension rollups.
N
actualsOverlay
The actuals overlay setting for the account.
N
attributeValues
List of accoun attribute value objects for this account.
N
displayAs
The display as setting for the account.
N
formula
The account formula.
N
decimalPrecision
The default decimal precision for the account.
N
exchangeRateType
The exchange rate type for this account.
N
suppressZeros
Returns whether the zero rows should be suppressed for the account on sheets.
N
startExpanded
Returns whether the account starts expanded on the sheet.
N
dataEntryType
The data entry type setting for this account.
N
dataPrivacy
The data privacy setting for this account.
N
linkedAccountMappings
List of LinkedAccountMapping.
N
Sheet accessibility object
Name
Description
Required
Type
Default
usernames
List of usernames to add to the sheet.
Must come in the form of valid email addresses.
N
string array
excludedFromWorkflow
Updates the "Excluded From Workflow" checkbox in the sheet accessibility settings.
N
boolean
false
Sample Response
204
Successful repsonse is blank with status code 204.

DELETE

Request URI
/sheet/cube/definition
Delete the cube sheet definition matching the given query parameter. If a sheet with the matching identifier does not exist, then not found error will occur.
Sample Request by Name
https://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/cube/definition?name=Sales Cube
Sample Request Header
Accept-Language: en
Sample Request Body
<None>
Query Parameters
Name
Description
Required
name
The name of the cube sheet.
N
instanceCode
The instanceCode to retrieve values from. For example, GLOBO. If no instanceCode is specified, the default instance of the user is used.
N
Sample Response
204
Successful response is blane with status code 204.