Skip to main content
Documentation
Documentation
Adaptive Planning
Last Updated: 2024-09-20
importStandardData

importStandardData

Updated in API v40 (September 13, 2024)
Category
Data submission
Description
Inserts or replaces data in standard accounts.
Permissions Required To Invoke
Import to All Locations
Erase Data (API v36+ to support REPLACE mode)
Parameters Required On Request
Credentials, ImportDataOptions, Version, RowData
includeDescendants
This method's request contains the parameters that will be used to determine which version will receive the supplied rows of data. Data can be imported into any standard account (GL Account, Custom Account, Assumption, or Exchange Rate) regardless of whether the account has been placed onto a sheet.
importStandardData can't import to accounts that use
Data Entry
 for
Override Formula Setting
.

Request Format


<?xml version='1.0' encoding='UTF-8'?>
<call method="importStandardData" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/>
<importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" useMappings="false" />
<version name="Budget 2004" isDefault="false" />
<rowData>
<header>Account|Level|Split Label|Product|Region|11/2005|01/2006</header>
<rows>
<row>70110|Corporate Plan||Bunnyrabbit Toy|Western-US|2037|4032</row>
</rows>
</rowData>
</call>
Each invocation of this API call must contain exactly one element of each of the listed types:
  • credentials
  • importDataOptions
  • version
  • rowData
  • header
  • rows
A mismatch between the number of pipe characters ( | ) in the header and the data will cause an error for API v30 or higher.
For API v36+, if the importDataOptions mode attribute is REPLACE, a scope element must also be specified:
Example: Replace Mode Request
Only available in API v36+
 

<?xml version='1.0' encoding='UTF-8'?>
<call method="importStandardData" callerName="a string that identifies your client application">
<credentials login="nobody@company.com" password="password" instanceCode="INSTANCE1"/>
<importDataOptions planOrActuals="Plan" allowParallel="true" moveBPtr="false" useMappings="false" mode="replace" />
<version name="Budget 2011" isDefault="false" />
<scope>
<accounts mode="explicit">
<account includeDescendants="false">30490</account>
<account includeDescendants="false">70313</account>
</accounts>
<levels mode="explicit">
<level includeDescendants="false">Development</level>
<level includeDescendants="true">Sales</level>
</levels>
<time mode="input" />
</scope>
<rowData>
<header>Account|Level|Split Label|Base Pay|CapitalAssetClass|Company|CountryRegion|01/2011</header>
<rows>
<row>30490|Asia Sales||120-150K|Furniture|ABC Cons|Washington|1</row>
<row>70313|Development||100-120K|OtherEquipment|ABC Cons|Maharashtra|2</row>
</rows>
</rowData>
</call>
credentials element
Tag Name
credentials
Description
All API calls must contain a singlecredentials 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 perform 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 the required permissions to invoke the method.
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,time period 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)
importDataOptions element
Tag Name
importDataOptions
Description
Specifies the options to be used when performing the import.
Attributes of the Element
Attribute Name
Required?
Value
Example
planOrActuals
Y
Set to one of "Plan" or "Actuals" to specify the type of data being imported. If this setting is in conflict with the version specified in theVersion tag, theVersion tag's value takes precedence and this setting is ignored.
Plan
moveBPtr
N
Used only when theplanOrActuals attribute is set toActuals. IfmoveBPtr is set totrue, the import will move the actuals availability pointer in the actuals version to be the latest time period found in the imported data. If set tofalse, the import will not affect which time periods show actuals on any version. This attribute must be set to false ifplanOrActuals is set toPlan.
false
allowParallel
Y
Used only when theplanOrActuals attribute is set toActuals. If set totrue, then an import will proceed even if there is already another actuals or transactions import in process for this instance. If set tofalse, then an attempt to import will fail if there is already an actuals or transactions import being processed for this instance.
false
useMappings
N
Specifies whether to use import mappings for accounts, plans and dimension values inside the row elements. Consideredtrue by default. Iffalse then the internal identifiers should be used: accounts are identified by code, levels and dimension values by name.
false
includeContext
N
Specifies whether messages may include the context block. Values arefalse (never show context) ortrue (show context if appropriate). If not specified,true is assumed.
false
displayNameEnabled
Only available in API v30+ for instances that enable display name.
N
displayNameEnabled=true indicates importStandardData should expect
Account Code
,
Level Code
,
Dimension Code
, and
Dimension Name Column
 in the payload when Enable Display Name is ON for the instance.
displayNameEnabled=false indicates the importStandardData API should continue following the pre-v30 API contract even when Enable Display Name is ON for the instance. The importStandardData API ignores the display name properties
Account Code
,
Level Code
,
Dimension Code
, and
Dimension Name Column
.
The default value for displayNameEnabled is "false".
false
splitsToUnsplit
Only available in API v40+
N
splitsToUnsplit=true allow splits to be imported into unsplit location with existing data. Default value for this attribute is false.
false
mode
Only available in API v36+
N
Specifies the import mode, which is either APPEND or REPLACE.
Append
Existing facts are updated or new facts added. No facts will be deleted.
Replace
The request must include a scope element representing the coordinates of the hypercube within which data will be replaced by that provided in the payload. Any existing data within the scope that does not have a matching coordinate in the payload will be deleted.
This mode attribute is supported from API v36 and later versions. Calling an earlier version of the API with mode="REPLACE" is an error.
The default value for mode when not specified is APPEND.
APPEND
Contents of the Element
(none)
version element
Tag Name
version
Description
Indicates which version should be used to receive the requested data. A version must be provided for each call.
Attributes of the Element
Attribute Name
Required?
Value
Example
name
N
The name of the version to be used to receive the data. Only one version can be accessed within a single API call. If a name is not provided, theisDefault flag must be set to true on this element.
To get a list of translated currency versions and their names, make anexportVersions request with currencyVersions=true in the include element.
Budget 2014
isDefault
N
If the caller wishes to access the current default version of the instance regardless of its name, this attribute can be set to true, in which case the name attribute of the tag (if present) is ignored. Otherwise, if this value is false or if this attribute is not present, a version with the supplied name must exist and be accessible to the user in order for this call to succeed.
false
Contents of the Element
(none)
scope element
Tag Name
scope
Only available in API version 36+
Description
Specifies the scope for this import.
Only allowed when the mode attribute of importDataOptions element is REPLACE.
Attributes of the Element
Attribute Name
Required?
Value
Example
eraseCellNotes
N
Specifies whether or not to erase cell notes in the scope. Must be one of 3 enumerated values:
NONE
 - Do not erase cell notes.
ALL
 - Erase all cell notes within the scope.
MODIFIED_ONLY
 - Erase cell notes for cells within the scope that are modified by the import. This includes previously empty cells that have facts imported into them, and cells whose facts are cleared.
If eraseCellNotes is not specified, it defaults to NONE.
NONE
Contents of the Element
One
time
 element, one
accounts
 element, and one
levels
 element all of which are mandatory.
accounts element
Tag Name
accounts
Only available in API version 36+
Description
Specifies the accounts for the import scope. If a specified account exists but there is no data for this account in the import data, data in this account will be removed for the time range and rest of the scope coordinates.
Only allowed when the mode attribute of importDataOptions element is REPLACE.
Attributes of the Element
Attribute Name
Required?
Value
Example
mode
Y
Specifies the mode for the account scope. Must be one of the following three options.
EXPLICIT
 - If this mode is specified, then we expect to see one or more account sub-elements that would determine the account scope for the import.
INPUT
 - When this mode is specified, the account scope will be determined by the unique set of accounts present in the import data.
Note: accounts mode="ALL" is not allowed for standard import scope.
EXPLICIT
Contents of the Element
If mode is
INPUT
, there must not be any <account> sub-elements.
If mode is
EXPLICIT
, there must be one or more <account> sub-elements.
If mode is
EXPLICIT
, and if any account code in an <account> sub-element is invalid, the entire <accounts> element, and by extension the <scope>, will be considered invalid. An error message will be included in the response for each invalid code.
account element
Tag Name
account
Only available in API version 36+
Description
Specifies the account code to be included in the scope for the import.
Only allowed when the mode attribute of importDataOptions element is REPLACE.
Attributes of the Element
Attribute Name
Required?
Value
Example
includeDescendants
N
If the account is a leaf account, includeDescendants has no effect.
If the account is a parent account then specifying this attribute as true will include all the leaf descendants of this account in the scope.
It is an error if the account is a parent account and includeDescendants is false. We can only import to leaf accounts.
This is an optional attribute and the default value will be considered as false.
true
selector
N
Specifies the account element content type:
  • Code. The account element content is an account code. Example:
    <account selector="code">30440</account>
    In this example, 30440 is an account code.
  • Type. The account element content is an account type. Example:
    <account selector="type">GL</account>
    In this example the account element type is all GL accounts. Currently, we support only "GL" and "CUSTOM" for account type for standard imports. All other content results in error.
The default value for selector is code.
Contents of the Element
The case-sensitive account code of the account used as part of the import scope. For example, AccountsPayable. The code must not be blank, and the account corresponding to the code must exist. The account cannot be a system or linked account. If the account is a calculated account, there must be a data-entry override for that account, otherwise, it is considered invalid.
If an account code is invalid, the entire <accounts> element, and by extension the <scope>, is considered invalid.
levels element
Tag Name
levels
Only available in API version 36+
Description
Specifies the level codes for the import scope. If a level code is specified here but there is no data for this level in the import data, data in this level will be removed for the time range and rest of the scope coordinates.
Only allowed when the mode attribute of importDataOptions element is REPLACE.
Attributes of the Element
Attribute Name
Required?
Value
Example
mode
Y
Specifies the mode for the level scope. Must be one of the following three options.
EXPLICIT
 - If this mode is specified, we expect to see one or more <level> sub-elements that would determine the level scope for the import.
INPUT
 - When this mode is specified, the level scope will be determined by the unique set of levels present in the import data.
ALL
 - When this mode is specified, the level scope will be all importable levels.
EXPLICIT
Contents of the Element
If mode is INPUT or ALL, there must not be any <level> sub-elements.
If mode is EXPLICIT, there must be one or more <level> sub-elements.
If mode is EXPLICIT, and if any level code in an <level> sub-element is invalid, the entire <levels> element, and by extension the <scope>, will be considered invalid. An error message will be included in the response for each invalid code.
level element
Tag Name
level
Only available in API version 36+
Description
Specifies the level code to be included in the scope for the import.
Only allowed when the mode attribute of importDataOptions element is REPLACE.
Attributes of the Element
Attribute Name
Required?
Value
Example
includeDescendants
N
If the level is a parent level then specifying this attribute as true will include all the leaf descendants of this level, including itself (the Only node) in the scope.
This is an optional attribute.
If the attribute is not provided the default value will be false. If the attribute is not provided or provided as false and the level specified is a parent level, then this would mean the import will consider the Only (example Engineering Only) node for that level for scope. Children of the level will not be included in the scope unless explicitly specified by other level elements.
true
Contents of the Element
Specifies the case-sensitive code of the level. For example, <level>Development</level>.
If there is an issue with the level code, e.g., a level where the code is not found, the entire <levels> and by extension the <scope> is considered invalid. An error message will be included in the response for each invalid code.
time element
Tag Name
time
Only available in API version 36+
Description
Specifies one or more time ranges that represent the scope for time for the import.
Only allowed when the mode attribute of importDataOptions element is REPLACE.
Attributes of the Element
Attribute Name
Required?
Value
Example
mode
Y
Specifies the mode for the time scope. Should be one of the following three options.
INPUT
 - When this mode is specified, the time scope will be determined by the time codes in the
<header>
 element. If the header contains two months, then the scope for the import will be these two months.
EXPLICIT
 - If this mode is specified, then we expect to see one or more timeRange sub-elements that would determine the time scope for the import.
VERSION
 - When this mode is specified, the time scope will be the start and end of the version including any initial balance period.
If the mode is INPUT or VERSION, no timeRange sub-element is permitted. If timeRange sub-elements are present this will be treated as an error .
INPUT
Contents of the Element
One or more timeRange elements unless mode is INPUT or VERSION.
timeRange element
Tag Name
timeRange
Only available in API version 36+
Description
Specifies a single time range for time scope.
Only allowed when the mode attribute of importDataOptions element is REPLACE.
Attributes of the Element
Attribute Name
Required?
Value
Example
start
Y
The start period for the import time range.
07/2021
end
Y
The end period for the import time range.
08/2021
Contents of the Element
One or more timeRange elements unless mode is INPUT or VERSION.
rowData element
Tag Name
rowData
Description
Container for the rows of data being imported.
Attributes of the Element
(none)
Contents of the Element
Exactly oneheader element and exactly onerows element.
header element
Tag Name
header
Description
Specifies the names and order of the columns of the data in the correspondingrows element.
Attributes of the Element
(none)
Contents of the Element
A line of text with vertical-bar-separated column names. These column names must correspond to the names of the dimensions or fields on the sheet, or to time period codes that can contain data. They are identical to the column names found in the Import Template for the sheet to which the data is being imported, with each column header separated from the next by a vertical bar or pipe symbol.
For instances that enable Display Name, the header doesn't support
"<dimension>"
 in combination with
"<dimension> Name"
 or
"<dimension> Code"
 in API v30 or higher for Adaptive Planning supported locales.
rows element
Tag Name
rows
Description
Container for one or morerow elements.
Attributes of the Element
(none)
Contents of the Element
One or morerow elements.
row element
Tag Name
row
Description
Data for a single row being imported.
Attributes of the Element
(none)
Contents of the Element
Data for the fields in a single row being imported, each field's value separated by a vertical bar or pipe symbol. The data fields must be in the same order as the line in the header element. If numbers in the values use thousands separators, they are assumed to be the comma separators used in the locale specified in the credentials of the request.

Response Format

These are examples of responses for successful and unsuccessful importing of standard account data.

Success Example


<?xml version='1.0' encoding='UTF-8'?>
<response success="true"></response>

Failed (with context)


<?xml version='1.0' encoding='UTF-8'?>
<response success="false">
<messages>
<message key="error-empty-account">
    <context>
        <col header="Account" value="" />
        <col header="Level" value="Corporate Plan" />
        <col header="Split Label" value="" />
        <col header="Product" value="Bunnyrabbit Toy" />
        <col header="Region" value="Western-US" />
        <col header="11/2005" value="2037" />
        <col header="01/2006" value="4032" />

    </context>
Account cannot be empty on row 1.

</message>
</messages>
</response>

Failed (no context)


<?xml version='1.0' encoding='UTF-8'?>
<response success="false">
<messages>
<message key="error-empty-account">Account cannot be empty on row 1.</message>

</messages>
</response>
response element
Tag Name
response
Attributes of the Element
Attribute Name
Required?
Value
Example
success
Y
Eithertrue orfalse, indicating whether the API call was successful or not. Even successful calls may contain warning messages in their response.
true
Contents of the Element
A single optionalmessages element.
messages element
Tag Name
messages
Description
Container for one or moremessage elements.
Attributes of the Element
(none)
Contents of the Element
One or moremessage elements.
message element
Tag Name
message
Description
Represents a message being sent from the system back to the caller. Messages are used for error messages when requests do not succeed, for warning messages when requests do succeed, and for confirmation messages upon success.
Attributes of the Element
Attribute Name
Required?
Value
Example
key
N
When given, a key is a way to identify a particular message or type of message, useful for purposes of automated error logging and recovery in client programs. Keys do not change under different locales of requests, even when the language of the message changes. Keys also are unlikely to change in the future due to wording adjustments or terminology changes.
invalid-attributevalueid
Contents of the Element
  1. The text of the message. This text is in the language of the locale specified on the request (assuming that locale is supported). The text may also contain variable information such as the number of rows which were processed, or the particular column or value that caused an error.
  2. An optional context element.
context element
Tag Name
context
Description
Container for one or more col elements.
Attributes of the Element
Attribute Name
Required?
Value
Example
none
Contents of the Element
One or more col elements.
col element
Tag Name
col
Description
Represents the context for the message. Gives a header/value pair so the row generating the message can be identified.
Attributes of the Element
Attribute Name
Required?
Value
Example
header
Y
The header of the column.
"Account"
value
Y
The value in the column.
"GL-29482-38233"
Contents of the Element
(none)