Skip to main content
Adaptive Insights
Knowledge and Support - Adaptive Insights

exportSheetDefinition

Category

Metadata retrieval

Description

Returns the definition of the given modeled or cube sheet.

Permissions Required To Invoke

IMP (import data) or MOD (create, edit, and delete sheets)

Parameters Required On Request

Credentials and a specification of which sheet is being requested.

Modeled Sheet Request Format

 <?xml version='1.0' encoding='UTF-8'?>
<call method="exportSheetDefinition" callerName="a string that identifies your client application">
    <credentials login="sampleuser@company.com" password="my_pwd"/>
    <modeled-sheet id="3"/>
   </call>

The call element contains a credentials element as well as a single modeled-sheet.

credentials element

Tag Name

credentials

Description

All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user (any audit trail or history of actions in the system will show that this user performed the action), and therefore the user must have the required permissions to per- form the action in order for the API call to succeed.

Attributes of the Element

Attribute Name

Required?

Value

Example

login

Y

The login name of the user invoking the API method. This user must have a role containing the permissions required for the method being invoked.

sampleuser@company.com

password

Y

The password of the user invoking the API method.

my_password

locale

N

Specify the locale to be used to interpret incoming numbers and dates, and to format outgoing numbers and dates (using the proper thousands separator, month names, and date formatting). The locale is also used to specify the language in which any system messages in the response should appear. If not specified, en_US (American English) is used.

fr_FR

instanceCode

N

If the user specified in the credentials has access to more than one instance of Adaptive Planning, this attribute can be used to specify that the user is intending to access an instance other than their default instance. If not specified, the user's default instance will be used. To determine the available instance codes, use the exportInstances API.

MYINSTANCE1

Contents of the Element

(none)

 

modeled-sheet element

Tag Name

modeled-sheet

Description

Identifies a single modeled sheet requested via an exportSheetDefinition API call.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

The internal system ID number for the sheet.

234

Contents of the Element

(none)

Modeled Sheet Response Format

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
   <output>
       <modeled-sheet id="11" prefix="Personnel" name="Personnel" description="Personnel Sheet" 
                              available-in-actuals="false" allow-splits="true" split-column-title="Is Split Child Row">
           <columns>
               <levels code="Plan" name="Plan" read-only="false" splittable="false" required="true">
                   <level id="1" />
                   <level id="7" />
               </levels>
               <text code="LastName" name="Last Name" read-only="false" splittable="false" required="false" />
               <text code="FirstName" name="First Name" read-only="false" splittable="false" required="false" />
               <text code="ID" name="ID" read-only="false" splittable="false" required="false" />
               <dimension code="JobCode" name="JobCode" read-only="false" splittable="false" required="false" id="9">
                   <value id="19" name="E1" />
                   <value id="20" name="E2" />
                   <value id="21" name="E3" />
               </dimension>
               <text-selector code="BenefitsSelector" name="Benefits" read-only="false" splittable="false" required="true" id="27">
                   <value id="208" name="No" />
                   <value id="209" name="Yes" />
               </text-selector>
               <date code="StartDate" name="Start" read-only="false" splittable="false" required="false" />
               <date code="EndDate" name="End" read-only="false" splittable="false" required="false" />
               <number code="HoursPerWeek" name="Hr/Week" read-only="false" splittable="false" required="false" />
               <text-selector code="per" name="per" read-only="false" splittable="false" required="true" id="28">
                   <value id="210" name="Yr" />
                   <value id="211" name="Hr" />
               </text-selector>
               <initial-balance code="PayRate" name="Pay Rate" read-only="false" splittable="false" required="false" id="143" />
               <display code="PayRate" name="Pay Rate Display Column" read-only="true" splittable="false" required="false" id="7" />
               <level-currency code="" name="Currency" read-only="true" splittable="false" required="false" id="8" />
           </columns>
       </modeled-sheet>
   </output>
</response>

 

The modeled-sheet element contains a single columns child holding one or more of these in the order defined for the sheet:

  1. levels
  2. dimension
  3. text-selector
  4. text
  5. number
  6. date
  7. initial-balance
  8. level-currency
  9. display
  10. timespan

response element

Tag Name

response

Attributes of the Element

Attribute Name

Required?

Value

Example

success

Y

Either true or false, indicating whether the API call was successful or not. Even successful calls may contain warning messages in their response.

true

obsolete

N

If present on the response tag and set to true, this attribute indicates that the version of the method or API which is being invoked has become obsolete and is officially deprecated by Adaptive Planning. While it continues to function at this time, it may cease functioning in a short while. Typically, this attri- bute is not present.

false

Contents of the Element

A single optional messages element, and exactly one required output element.

 

modeled-sheet element

Tag Name

modeled-sheet

Description

Represents a single modeled sheet being returned in the response to an export- Sheets API call.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

The internal system ID number for the sheet. This can be used to identify sheets in other API calls, such as exportSheetDefinition.

234

prefix

Y

The prefix of the sheet.

Capital

name

Y

The name of the sheet.

Capital Model

available-in-
actuals

Y

Can be true or false. Denotes whether the modeled sheet is available in actuals version or not.

true

description

N

The textual description of the sheet, if any.

This is the Capital
Model...

allow-splits

Y

True means the modeled sheet allows splits.

true

split-column-
title

N

The additional column title for import when allow-splits is enabled. Use a localized string if a locale is specified in the request. This attri- bute is only present when allow-splits is set to true and at least one column is splittable.

Is Split Child Row

Contents of the Element

A single columns element.

 

columns element

Tag Name

columns

Description

Container for one or more column elements.

Attributes of the Element

Attribute Name

Required?

Value

Example

(none)

Contents of the Element

One or more of the following elements, ordered as they appear on the sheet:

• levels
• dimension
• text-selector
• text
• number
• date
• initial-balance
• level-currency
• display
• timespan

 

levels element

Tag Name

levels

Description

Represents the "level" column on a modeled sheet. Container for one or more level elements.

Attributes of the Element

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

true

Contents of the Element

One or more level elements.

 

level element

Tag Name

level

Description

One of the levels defined for this company which is on this sheet (or on which this sheet has been placed). Level metadata, including the hierar- chical structure, can be obtained by a call to exportLevels.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

Internal numeric identifier for the level.

42

Contents of the Element

(none)

 

text element

Tag Name

text

Description

Represents a column on the sheet which holds user-entered text.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

Contents of the Element

(none)

 

dimension element

Tag Name

dimension

Description

One of the dimensions defined for this company. Represents a column on the sheet which holds the dimension.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

Contents of the Element

One or more value elements, each of which is a valid selectable value in the dimension for this sheet. If a value of the dimension is not included here, that value cannot be used on data rows on this sheet.

 

value element

Tag Name

value

Description

One of the values defined for this dimension or text-selector. Complete dimension metadata, including its hierarchical structure, can be obtained by a separate call to exportDimensions.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

Internal numeric identifier for the value.

42

name

Y

Printed representation of the value.

Mexico

Contents of the Element

(none)

 

text-selector element

Tag Name

text-selector

Description

Custom list of values defined for this sheet. Represents a text selector column on a modeled sheet.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

true

id

Y

Internal numeric identifier.

42

Contents of the Element

One or more value elements.

 

number element

Tag Name

number

Description

Represents a column on the sheet which holds a user-entered number.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

Contents of the Element

(none)

 

date element

Tag Name

date

Description

Represents a column on the sheet which holds a user-entered date.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

Contents of the Element

(none)

 

initial-balance element

Tag Name

initial-balance

Description

Represents a column on the sheet that holds a user-supplied value for the initial balance of an account with a formula that determines the monthly change in the account's value.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

id

Y

Internal numeric identifier of the account associ- ated with this column.

42

Contents of the Element

(none)

 

level-currency element

Tag Name

level-currency

Description

Represents a column on the sheet that displays the code for the currency associ- ated with each row. This is the currency of the level where the row is located.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column. For level-currency elements, this value is always true.

true

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

id

Y

Internal numeric identifier.

42

Contents of the Element

(none)

 

display element

Tag Name

display

Description

Represents a column on the sheet that holds a row-based, read-only calculation.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

id

Y

Internal numeric identifier.

42

Contents of the Element

(none)

 

timespan element

Tag Name

timespan

Description

At most one per sheet, this represents a timespan set of columns, which appear on the right of the sheet and can hold periodic data.

Attributes of the Element

Attribute Name

Required?

Value

Example

code

Y

A symbolic identifier for the column, used in sheet formulas and references.

MyColumn

name

Y

Displayable title of the column, as seen on the sheet.

My Column

read-only

Y

True if the column is marked as read-only on the sheet, false if values can be entered into the column.

false

splittable

Y

True if splits of rows can have different values for this column, false if splits must have the same value as their parent.

true

required

Y

True if this attribute is a mandatory field.

false

id

Y

Internal numeric identifier of the account associ- ated with this timespan.

42

Contents of the Element

(none)

 Cube Sheet Request Format

<?xml version='1.0' encoding='UTF-8'?>
<call method="exportSheetDefinition" callerName="a string that identifies your client application">
     <credentials login="sampleuser@company.com" password="my_pwd"/>
     <cube-sheet id="4"/>
   </call>

The call element contains a credentials element, as well as a single cube-sheet.

credentials element

Tag Name

credentials

Description

All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user (any audit trail or history of actions in the system will show that this user performed the action), and therefore the user must have the required permissions to per- form the action in order for the API call to succeed.

Attributes of the Element

Attribute Name

Required?

Value

Example

login

Y

The login name of the user invoking the API method. This user must have a role containing the permissions required for the method being invoked.

sampleuser@company.com

password

Y

The password of the user invoking the API method.

my_password

locale

N

Specify the locale to be used to interpret incoming numbers and dates, and to for- mat outgoing numbers and dates (using the proper thousands separator, month names, and date formatting). The locale is also used to specify the language in which any system messages in the response should appear. If not specified, en_US (American English) is used.

fr_FR

instanceCode

N

If the user specified in the credentials has access to more than one instance of Adaptive Planning, this attribute can be used to specify that the user is intending to access an instance other than their default instance. If not specified, the user's default instance will be used. To determine the available instance codes, use the exportInstances API.

MYINSTANCE1

Contents of the Element

(none)

 

cube-sheet element

Tag Name

cube-sheet

Description

Identifies a single cube sheet requested via an exportSheetDefinition API call.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

The internal system ID number for the sheet.

234

Contents of the Element

(none)

 Cube Sheet Response Format

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
<output>
   <cube-sheet id="17" prefix="ExpenseCube" name="Expense Cube" description="">
     <dimensions>
       <dimension id="12" uncategorized="false" rollup="false">
         <value id="102"/> <!-- a leaf value, no rollup, no uncategorized -->
         <value id="90"/>
       </dimension>
       <attribute id="14" uncategorized="true" rollup="true">
         <value id="74" rollup="true" />
         <value id="75" uncategorized="true" />
         <value id="76" rollup="true" />
         <value id="76" uncategorized="true"/> <!-- notice same id twice -->
         <value id="80">
       </attribute>
       <levels>
         <level id="1"/>
         <level id="7"/>
       </levels>
       <accounts>
         <account id="218"/>
         <account id="217"/>
       </accounts>
       <time/>
     </dimensions>
   </cube-sheet>
</output>
</response>

The cube-sheet element contains a single dimensions child holding these in the order defined for the sheet:

• dimension (one or more)
• attribute (zero or more)

• levels (one)
• accounts (one)

• time (one)

 

response element

Tag Name

response

Attributes of the Element

Attribute Name

Required?

Value

Example

success

Y

Either true or false, indicating whether the API call was successful or not. Even successful calls may contain warning messages in their response.

true

obsolete

N

If present on the response tag and set to true, this attribute indicates that the version of the method or API which is being invoked has become obsolete and is officially deprecated by Adaptive Planning. While it continues to function at this time, it may cease functioning in a short while. Typically, this attri- bute is not present.

false

Contents of the Element

A single optional messages element, and exactly one required output element.

 

output element

Tag Name

output

Attributes of the Element

Attribute Name

Required?

Value

Example

(none)

Contents of the Element

A single required cube-sheets element. This output wrapper is standard on all API responses and encloses the valid output of any successful API call.

 

cube-sheet element

Tag Name

cube-sheet

Description

Represents a single cube sheet being returned in the response to an exportSheets API call.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

 

The internal system ID number for the sheet. This can be used to identify sheets in other API calls, such as exportSheetDefinition.

34

prefix

 

The prefix of the sheet.

ExpenseCube

name

 

The name of the sheet.

Expense Cube

description

 

The textual description of the sheet, if any.

 

Contents of the Element

(none)

 

dimensions element

Tag Name

dimensions

Description

Container for the dimensions of the sheet.

Attributes of the Element

Attribute Name

Required?

Value

Example

(none)

Contents of the Element

One or more levels, dimension, accounts, time elements.

 

attribute element

Tag Name

attribute

Description

One of the attributes placed on this cube sheet. Attribute metadata, including its hierarchical structure, can be obained by a call to exportAttributes.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

The internal numeric identifier for the attribute.

34

uncategorized

Y

True means the uncategorized element of the attribute itself (the “root uncategorized” ele- ment) is available as a selection on the cube.

true

rollup

Y

True means the rollup element of the attribute itself (the rollup of all elements) is available as a selection on the cube.

true

Contents of the Element

One or more value elements, indicating which values of the attribute are available on the sheet.

 

value element

Tag Name

value

Description

One of the values for this dimension which has been marked as available on the sheet. The same value id can appear up to twice: with and without uncategorized set to true. Dimension metadata, including its hierar- chical structure, can be obtained by a call to exportDimensions.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

Internal numeric identifier for the dimen- sion value.

34

rollup

N

true indicates the rollup of this dimension value. Only allowed if the value has child values in the dimension. If the attribute is missing, false is used.

true

uncategorized

N

true indicates the uncategorized value of this dimension value. Only allowed if the value has child values in the dimension. If the attribute is missing, false is used.

true

Contents of the Element

(none)

 

levels element

Tag Name

levels

Description

Enforced container for one or more level elements. Individual levels are returned, even if they affect visibility only. Data can be imported into any level.

Attributes of the Element

Attribute Name

Required?

Value

Example

(none)

Contents of the Element

One or more level elements.

 

level element

Tag Name

level

Description

A level found on this sheet, on which this sheet appears. Level metadata, including its hierarchical structure, can be obtained by a call to exportLevels.

 

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

Internal numeric identifier for the level.

12

Contents of the Element

(none)

 

accounts element

Tag Name

accounts

Description

Enforced container for one or more account elements. Individual accounts are returned, even if they affect visibility only. Data can be imported into any input account.

Attributes of the Element

Attribute Name

Required?

Value

Example

(none)

Contents of the Element

One or more account elements.

 

account element

Tag Name

account

Description

One of the accounts defined for this cube sheet. Account metadata, including its hierarchical structure, can be obtained by a call to exportAccounts.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

Internal numeric identifier for the account.

23

Contents of the Element

(none)

 

time element

Tag Name

time

Description

Enforced time dimension.

Attributes of the Element

Attribute Name

Required?

Value

Example

(none)

Contents of the Element

(none)

  • Was this article helpful?