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

exportData

Category

Data retrieval

Description

Returns a set of data from the requested version in the request instance.

Permissions Required To Invoke

None (must be valid credentials for the instance)

Parameters Required On Request

Credentials, Version, Format, Filters

 

This method's request contains the parameters that will be used to search the data in the specified version and return values which match the requested filters and format. This is the basic method used to retrieve data from Adaptive, and can be used to retrieve values from any accounts, including standard accounts, GL accounts, modeled accounts, cube accounts, custom accounts, metric accounts, assumptions, and exchange rates.

See customReportValues for a more targeted approach to data retrieval.

Request Format

<?xml version='1.0' encoding='UTF-8'?>
<call method="exportData" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/>
<version name="Budget 2014" isDefault="false"/>
<format useInternalCodes="true" includeUnmappedItems="false"/>
<filters>
   <accounts>
     <account code="A100" isAssumption="true" includeDescendants="false"/>
     <account code="L100" isAssumption="false" includeDescendants="true"/>
   </accounts>
   <levels>
     <level name="Development" isRollup="true" includeDescendants="true"/>
     <level name="QA" isRollup="false" includeDescendants="false"/>
   </levels>
   <timeSpan start="11/2013" end="12/2014"/>
   <dimensionValues>
     <dimensionValue dimName="Customer" name="A Corp" directChildren="true"/>
     <dimensionValue dimName="Region" name="" uncategorized="true" directChildren="false"/>
   </dimensionValues>
</filters>
<dimensions>
   <dimension name="Product"/>
   <dimension name="CountryRegion"/>
</dimensions>
<rules includeZeroRows="false" includeRollups="false" markInvalidValues="false" markBlanks="false" timeRollups="single">
   <currency useCorporate="false" useLocal="false" override="AUD"/>
</rules>
</call>

 

Each invocation of this API call must contain exactly one element of each of the listed types:

A request also may contain one of the following elements:

  •  

    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).

    The Export Capabilities role permission in the Planning UI does not affect exportData.

    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)

     

    version element

    Tag Name

    version

    Description

    Indicates which version should be used to retrieve 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, the isDefault flag must be set to true on this 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)

     

    format element

    Tag Name

    format

    Description

    Indicates the type of formatting that should be used on the individual fields of the data to be returned.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    useInternalCodes

    Y

    Set to "true" to have account codes emitted using the codes entered in Account Administration for each account. Set to "false" to have account codes mapped in the output data using the Export Account Mappings found on the Export tab.

    true

    includeUnmappedItems

    N

    This attribute only applies if useInternalCodes is false and export mappings are used. If not otherwise specified, accounts which have no Export Account Mapping on the Export tab will not be emitted in the output. If includeUnmappedItems is set to "true", then accounts which have no Export Account Mapping will be emitted, using their internal account codes (the ones set in Account Administration) as their codes, yielding a blend of mapped and unmapped accounts in the data, but a complete set of data. If this flag is set to "false", some requested accounts may not be emitted, if they have no Export Account Mapping.

    false

    Contents of the Element

    (none)

    filters Element

    Tag Name

    filters

    Description

    Holds the specification for the filters which determine which data from the requested version is retrieved by the API. This element specifies the accounts, levels, months, and dimension values which will be retrieved.

    Attributes of the Element

    (none)

    Contents of the Element

    A single required accounts element, a single optional levels element, a single required timeSpan element, and an optional single dimensionValues element.

     

    accounts element

    Tag Name

    accounts

    Description

    Container for one or more account elements.

    Attributes of the Element

    (none)

    Contents of the Element

    One or more account elements.

     

    account element

    Tag Name

    account

    Description

    Specifies an account to have its data exported in the exportData API call. If more than one account element is placed within the accounts element, all accounts which match any of the account elements will be exported. If any given account element results in no accounts which match it, that element is ignored while the other elements still apply.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    code

    Y

    The code of the account to be exported. This code is as specified in Account Administration.

    Current_Assets

    isAssumption

    Y

    Indicates whether the code specifies an assumption or a non-assumption account. A single code can be used for both an assumption and account in Adaptive Planning, so this flag indicates which type of account is being specified.

    false

    includeDescendants

    Y

    Indicates whether the export should include all descendants of the specified account or not. If set to true, all children of this account will be exported, as will their children, etc. If set to false, this account will be exported as a single rollup account value.

    true

    Contents of the Element

    (none)

     

    levels element

    Tag Name

    levels

    Description

    Container for one or more level elements.

    Attributes of the Element

    (none)

    Contents of the Element

    One or more level elements. If the request includes inaccessible levels, there will be only one level element, which represents the top level of the organization.

     

    level element

    Tag Name

    level

    Description

    Specifies an organization level to have its data exported in the exportData API call. If more than one level element is placed within the levels element, all specified levels will be exported. If any given level element has no matching levels in the instance, that element is ignored while the other elements still apply.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    name

    Y

    The name of the level to be exported. This name is as specified in Organization Administration.

    Development

    isRollup

    Y

    If this level has children, isRollup="true" will output the rollup value for the level (including the values of all of its children) and
    isRollup="false" will only output the uncategorized value for the level (the values entered in Edit Data for that level). If this level does not have children, the isRollup must be set to false (or omitted from the tag entirely).

    false

    includeDescendants

    Y

    Indicates whether the export should include all descendants of the specified level or not. If set to true, all children of this level will also be exported, as will their children, etc. If set to false, this level will be exported alone. Note this is different than isRollup: isRollup affects which value will be output for this level, while include Descendants indicates whether descendants should also be included in the export. If both isRollup and includeDescendants are set to true and the level is a parent level, the output will contain values for both rollup and non-rollup (uncategorized) levels for this level and each of its descendants.

    true

    Contents of the Element

    (none)

     

    timeSpan element

    Tag Name

    timeSpan

    Description

    Indicates which time periods should be returned in the response. Time periods between the specified range, inclusive, are included in the output as separate columns of data; they are not aggregated or rolled up.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    start

    Y

    The code of the first time period in the range of time periods to have their data exported. The start time period must be a leaf time period.

    01/2015

    end

    Y

    The code of the last time period in the range of time periods to have their data exported. The end time period must be a leaf time period.

    03/2015

    Contents of the Element

    (none)

     

    dimensionValues element

    Tag Name

    dimensionValues

    Description

    Container for one or more dimensionValue elements. This element is optional and should not appear if no dimension value filtering is desired.

    Attributes of the Element

    (none)

    Contents of the Element

    One or more dimensionValue elements.

     

    dimensionValue element

    Tag Name

    dimensionValue

    Description

    Indicates that the exported data should contain only values which match the specified dimensionValue. If more than one dimensionValue element is within the dimensionValues element, then data must match all specified dimensions, but any of the specified dimension values within each dimension in order to be exported. For example, if a request specifies dimension values of Region=East, Region=West, and Product=Product_A, then data must match either East or West Region, but must also match Product_A Product in order to be exported.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    dimName

    N

    The name of the dimension to which the dimension value (see name attribute below) belongs.

    Region

    name

    N

    The name of the dimension value to be exported.

    US West

    directChildren

    N

    If set to true, this will cause the API to export rollup data for each of the direct children of this dimension value, but not a rollup for the value itself. In other words, this will cause exportData to export the values "one level down" in the dimension tree from the specified value. If not specified, defaults to false.

    false

    uncategorized

    N

    If set to true, matches the "uncategorized" value of the dimension value and not the values of any of its descendant values (if any). Has no effect on dimension values with no children. If not specified, defaults to false.

    true

    uncategorizedOfDimension

    N

    Specify the uncategorizedOfDimension in place of the dimName/name attributes.

    • If specified the value of the attribute should be an internal system ID number of a dimension (not a dimension value) and the filter is specifying that data must be completely uncategorized in this dimension in order to match the filter.
    • The directChildren and uncategorized attributes will be ignored and assumed to be false and true respectively.
    • Ignored if dimName is specified.

    15

    directChildrenOfDimension

    N

    Specify the directChildrenOfDimension in place of the dimName/name attributes.

    • If specified the value of the attribute should be an internal system ID number of a dimension (not a dimension value) and the filter is specifying all the first level dimension values of the dimension.

    • The directChildren and uncategorized attributes will be ignored and assumed to be true and false respectively.

    • Ignored if dimName or uncategorizedOfDimension is specified.

    12

    id

    N

    Specify the id in place of the dimName/name attributes.

    • The internal system ID number of the dimension value to be exported. Should be specified in place of the dimName/ name attributes to specify the dimension value. To determine internal IDs, see the exportDimensions API.

    • Ignored if either dimName, uncategorizedOfDimension or directChildrenOfDimension is specified.

    14

    Contents of the Element

    (none)

     

    dimensions element

    Tag Name

    dimensions

    Description

    Container for one or more dimension elements.

    Attributes of the Element

    (none)

    Contents of the Element

    One or more dimension elements.

     

    dimension element

    Tag Name

    dimension

    Description

    Indicates that the exported data should be broken down, or sliced, by the specified dimension. Note that this tag is not a part of the filters tag and does not control filtering: it instead controls how many rows are exported for each account/level combination. For each dimension specified in the dimensions tag, each existing combination of values will be exported as a separate row of data. Each dimension present in the dimensions element also causes an extra column to appear in the output, labeled with that dimension name.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    name

    Y

    Name of the dimension by which the export should be sliced. Rows of data in the export which cannot be sliced by the dimension will appear only once and will show the dimension name itself in the column where the dimension value name for this dimension would appear.

    Customer

    Contents of the Element

    (none)

     

    rules element

    Tag Name

    rules

    Description

    Specifies some extra output rules that control which types of rows are emitted and how some field values will be rendered.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    includeZeroRows

    N

    Set to "true" to have rows emitted even if they contain only zeroes or blanks. Set to "false" to have rows without data omitted from the output. Default value is false.

    true

    includeRollups

    N

    If set to true, rollup values for all accounts and levels in the filters tag will be included in addition to the values for their descendants. This attribute does not affect how custom dimensions specified in dimensionValue filters or in the dimensions tag behave. Default value is false.

    The includeRollups flag only applies when no explicit filtering is being applied for accounts or for levels.  If any individual accounts are included in a filter, you need to specify the individual rollup accounts if you want them included.

    false

    markInvalidValues

    N

    If set to true, the export will add the letter "I" to invalid values. Otherwise adds "=NA()" to invalid values, to make them Excel compatible. Default value is false.

    false

    markBlanks

    N

    If set to true, blank values will be output as "B". Otherwise, values which are blank will be output as zeroes. Default value is false.

    false

    timeRollups

    N

    Has three possible values: true, false, and single. If set to true, quarter and year rollups will appear in their “proper place” within the exported span of months. Quarter rollups appear immediately after the last month of their quarter, and year rollups appear immediately after the quarter rollup for their last quarter. If set to single, no individual months, quarters, or years are returned and only a single time rollup of all months covered in the timespan element is returned. If set to false, only individual months are returned, with no time rollup columns. Default value is false.

    false

    Contents of the Element

    An optional currency element to specify what currency should be used in the export.

     

    currency element

    Tag Name

    currency

    Description

    Indicates which currency should be used in the output when emitting the values of currency accounts.

    Attributes of the Element

    Attribute Name

    Required?

    Value

    Example

    useCorporate

    N

    Only one of the three attributes can be set for a currency element. If useCorporate is set to true, it indicates that the "corporate currency" (the currency at the top of the organization tree) should be used. Default value is false.

    false

    useLocal

    N

    Only one of the three attributes can be set for a currency element. If useLocal is set to true, it indicates that currency values should be emitted in the currency of the Organization Level where they reside. Each row of the output indicates an Organization Level, and currency values on that row will be in that level's currency. Default value is false.

    false

    override

    N

    Only one of the three attributes can be set for a currency element. If override is present, it must specify the three-letter currency code of one of the configured currencies for the instance. When specified, all currency amounts in the export will be converted to that currency.

    AUD

    Contents of the Element

    (none)

    Response Format

    <?xml version='1.0' encoding='UTF-8'?>
    <response success="true">
    <messages>
       <message key="warning-invalid-timespan-start">Ignoring start of timespan, which precedes start of version; timsepan start: Nov-2009, version start date: Jan-2014</message>
    </messages>
    <output><![CDATA[
      Account Name,Account Code,Level Name,[01/2014,02/2014,03/2014,04/2014,05/2014,06/2014,07/2014,08/2014,09/2014,10/2014,11/2014,12/2014]
    "Benefits",30120,"Engineering (Rollup)",10653.75,10653.75,10653.75,11506.05,11506.05,11506.05,11506.05,11506.05,11506.05,10462.05,10426.05,10426.05
    "Furniture",70310,"Engineering (Rollup)",1740.0,2610.0,2610.0,2610.0,2610.0,2610.0,2610.0,2610.0,2610.0,2610.0,2610.0,2610.0
      ...
    ]]>
    </output>
    </response>
    

    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 attribute is not present.

    false

    Contents of the Element

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

     

    messages element

    Tag Name

    messages

    Description

    Container for one or more message elements.

    Attributes of the Element

    (none)

    Contents of the Element

    One or more message 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 which caused an error.

     

    output element

    Tag Name

    output

    Description

    Contains the resulting data of the export in an enclosed CDATA block.

    Attributes of the Element

    (none)

    Contents of the Element

    A CDATA block containing the CSV-formatted data of the export. Rows are separated by newline characters. The first row of returned data is the set of "column headers" describing the format of each of the following rows. Dimensions and filtering elements are listed first, followed by the series of requested time period values. Time period codes and system-generated labels such as the "(Rollup)" suffix on rollup levels are translated to the locale of the request when possible. Values are emitted in normalized form, without commas, using a period as the decimal separator.

  • Was this article helpful?