跳至主要內容
文件
文件
Adaptive Planning
importCubeData

importCubeData

Category
Data submission
Description
Inserts or replaces data in a cube sheet. This method can also be used to delete data from a cube sheet by importing zeroes to locations in the cube. Importing a zero into a cube sheet will erase the data at the location of the zero.
Permissions Required To Invoke
Import
Parameters Required On Request
Credentials, ImportDataOptions, Version, Sheet, RowData
This method's request contains the parameters that will be used to determine which sheet and which version will receive the supplied rows of data. This method can also be used to delete data from a cube sheet by importing zeroes to locations in the cube. Importing a zero into a cube sheet will erase the data at the location of the zero.

Request Format


<?xml version='1.0' encoding='UTF-8'?>
<call method="importCubeData" 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"/>
<version name="Budget 2014" isDefault="false" />
<sheet name="Sales Cube" isUserAssigned="false" />
<rowData>
   <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|06/2014|07/2014|08/2014|09/2014|01/2015</header>
   <rows>
     <row>Coffee table|Argentina|Do-All 15 Vertical|Aeropostale|Price|Corporate Plan|0|0|0|0|0</row>
   </rows>
</rowData>
</call>
Each invocation of this API call must contain exactly one element of each of the listed types:
  • credentials
  • importDataOptions
  • version
  • sheet
  • rowData
Additionally, when the mode is specified as REPLACE the scope element must be specified.
A mismatch between the number of pipe characters ( | ) in the header and the data will cause an error for API v30 or higher.
Sample request specifying replace mode with scope: 
<?xml version='1.0' encoding='UTF-8'?>
<call method="importCubeData" callerName="a string that identifies your client application">
 <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/>
 <version name="Budget 2022" isDefault="true" />
 <sheet name="Expense Cube" isUserAssigned="false" />
 <importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" mode="REPLACE" />
 <!-- Scope parameter specifying the import scope.-->
 <scope>
 <!-- Specifies the time scope for import. All values will be specified as time codes.-->
  <time mode="EXPLICIT">
   <timeRange start="01/2021" end="10/2021" />
  </time>
  <!-- Specifies list of accounts in the scope. All values will be specified as code field.-->
  <accounts mode="EXPLICIT">
   <account includeDescendants="true">Op_Expense_Inputs</account>
   <account includeDescendants="true">Op_Expense_Drivers</account>
  </accounts>
  <!-- Specifies list of levels in the scope. All values will be specified as code field.-->
  <levels mode="INPUT"/>
 </scope>
 <rowData>
  <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|01/2022|02/2022|03/2022|04/2022|05/2022|06/2022|07/2022|08/2022|09/2022|10/2022|11/2022|12/2022</header>
  <rows>
   <row>Coffee Table|Argentina|Do-All 15 Vertical|Aeropostale|Units|Development|44567.33|21345.77|22341.43|65567.32|298145.12|12641.83|77821.53|7766342.09|211441.21|88712.43|61940.41|662341.03|775420.25|800345.17</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 importCubeData 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 importCubeData API should continue following the pre-v30 API contract even when Enable Display Name is ON for the instance. The importCubeData API ignores the display name properties
Account Code
,
Level Code
,
Dimension Code
, and
Dimension Name Column
.
The default value for displayNameEnabled is "false".
false
mode
Available in API v32+
N
Specifies the import mode, which is one of APPEND or REPLACE.
APPEND – Existing facts are updated or new facts inserted. No facts will be deleted.
REPLACE – The caller must specify a scope element representing the coordinates of the cube within which data will be replaced with that provided in the payload. All existing data within the scope will be replaced with the data in the payload of the call.
This option is supported from API v32 and above versions. Calling the API with previous versions will result in an error.
The default value for mode when not specified is APPEND.
REPLACE
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 totrue on this element.
Budget 2012
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)
sheet element
Tag Name
sheet
Description
Indicates which sheet should receive the imported data. Each API call can target only one sheet's data.
Attributes of the Element
Attribute Name
Required?
Value
Example
name
Y
The name of the sheet to which the data will be imported.
Personnel
isUserAssigned
N
Indicates the sheet is a user-assigned sheet. If not specified, defaults to false, which indicates it's a level-assigned sheet.
false
Contents of the Element
(none)
scope element
Tag Name
Scope
Description
Specifies the scope for this import. Only applicable when mode for import is specified as REPLACE.
Available in API v32+
Attributes of the Element
Attribute Name
Required?
Value
Example
mode
Y
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.
time element
Tag Name
Time
Description
Specifies one or more time ranges that represent the scope for time for the import.
Available in API v32+
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 specified and is either INPUT or VERSION, then no timeRange element should be included. If present, this would be treated as an error condition.
Specifying VERSION takes the Version start date into consideration even when the Plan start date comes after the Version start date.
INPUT
Contents of the Element
One or more timeRange elements unless mode is INPUT or VERSION.
timeRange element
Tag Name
TimeRange
Description
Specifies a single time range for time scope.
Available in API v32+
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
(none)
accounts element
Tag Name
accounts
Description
Specifies the account codes for the import scope. If an account code exists here 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.
Available in API v32+
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.
  • ALL - When this mode is specified, the account scope will be all of the accounts for the import. For a cube sheet import this will represent all importable accounts for that cube sheet.
If the mode is specified and is either INPUT or ALL then no account sub-element should be included. If present this would be treated as an error condition.
EXPLICIT
Contents of the Element
One or more account elements unless mode is INPUT or ALL.
account element
Tag Name
account
Description
Specifies the account code to be included in the scope for import.
Available in API v32+
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.
If the account is a parent account and includeDescendants is false, this account element will be treated as if it was not specified.
The rationale for this treatment of parent accounts is that a leaf account may sometimes be promoted to become a parent account and the import specification may not be updated in time to reflect this change. Ignoring a parent account with includeDescendants=false prevents unintentional data deletion.
This is an optional attribute and the default value will be considered as false.
true
Contents of the Element
Specifies the account code of the account used as part of the import scope. For example, Operational_Expense.
levels element
Tag Name
levels
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.
Available in API v32+
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, then 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.
If the mode is specified and is either INPUT or ALL then no level sub-element should be included. If present this would be treated as an error condition.
INPUT
Contents of the Element
One or more level elements unless mode is specified as INPUT or ALL.
level element
Tag Name
level
Description
Specifies the level code to be included in the scope for import.
Available in API v32+
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 considered in scope unless explicitly specified with other level elements.
true
Contents of the Element
Specifies the level code of the level as part of the import scope. For example, Development.
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 cube data.

Success Example


<?xml version='1.0' encoding='UTF-8'?>
<response success="true">
<messages>
  <message key="warning-no-data-imported-dimension-unmapped">Warning: Row 3 was not imported because Coffeee table is unmapped.</message>
</messages>
</response>

Failed (with context)


<?xml version='1.0' encoding='UTF-8'?>
<response success="false">
   <messages>
       <message key="err-incomplete-cube-row">
           <context>
               <col header="ProductFurniture" value="Coffee table" />
               <col header="CountryRegion" value="" />
               <col header="Account" value="Do-All 15 Vertical" />
               <col header="Level" value="Aeropostale" />
               <col header="06/2014" value="Price" />
               <col header="07/2014" value="Corporate Plan" />
               <col header="08/2014" value="0.0" />
               <col header="09/2014" value="0.0" />
               <col header="01/2015" value="0.0" />
     
           </context>
     Row 1 is missing a value.
   
       </message>
       <message key="err-no-rows">You must import at least one row of data.</message>
     </messages>
</response>

Failed (no context)


<?xml version='1.0' encoding='UTF-8'?>
<response success="false">
   <messages>
       <message key="err-incomplete-cube-row">Row 1 is missing a value.</message>
       <message key="err-no-rows">You must import at least one row of data.</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
  • 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.
  • 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)