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 Insights, 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" strataId="51"> <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:
- levels
- dimension
- text-selector
- text
- number
- date
- initial-balance
- level-currency
- display
- 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 Insights. 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 |
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 attribute is only present when allow-splits is set to true and at least one column is splittable. |
Is Split Child Row |
strataId | Y | The strata ID associated with this modeled sheet | 2 |
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 |
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. |
|
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 Insights, 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="" strataId="5"> <dimensions> <dimension id="12" uncategorized="false" rollup="false" name="Product Item"> <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="245" code="" /> <account id="246" code="SalesCubeWithAttribute.Unit_Price" /> <account id="247" code="SalesCubeWithAttribute.Unit_Sold" /> <account id="249" code="SalesCubeWithAttribute.SalesMetric" /> <account id="250" code="SalesCubeWithAttribute.SalesDimMetric" /> </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 Insights. 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. |
||
strataId | Y | the strata id of the sheet | 5 |
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. |
dimension element |
|||
Tag Name |
dimension |
||
Description |
One of the dimensions defined for this cube sheet. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
id |
Y |
The internal numeric identifier for the dimension. |
34 |
uncategorized |
Y |
True means the uncategorized element of the dimension itself (the “root uncategorized” ele- ment) is available as a selection on the cube. |
true |
rollup |
Y |
True means the rollup element of the dimension itself (the rollup of all elements) is available as a selection on the cube. |
true |
name Available in API v22+ |
Y | Name of this dimension. | Product Item |
Contents of the Element |
|||
One or more value elements, indicating which dimension values are available on the sheet. |
attribute element |
|||
Tag Name |
attribute |
||
Description |
One of the attributes placed on this cube sheet. Attribute metadata, including its hierarchical structure, can be obtained 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 |
name Available in API v22 + |
Y | The name of the attribute. | Store Type |
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 |
code Available in API v22+ |
N | The account code for the account. | SalesCubeWithAttribute.Unit_Price |
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) |