exportDimensions
This API only supports user Concept: Access Rules in API v22 and above.
Category | Metadata retrieval |
Description | Returns metadata for the complete list of all dimensions in the system. |
Permissions Required To Invoke | None (must be valid credentials for the instance) |
Parameters Required On Request | Credentials |
This method's request contains only a credentials tag to identify and authorize the calling user. Once verified, the method returns an XML document describing the complete set of custom dimensions in the system, including all of their member values. This method does not return any of the required system dimensions such as Version, Time, or Accounts, each of which is available in its own metadata API call. Member values within a dimension are returned in tree form, with parent members containing their children.
You can find dimension IDs using an
exportDimensions
request with no dimensionIDs element. This produces a list of all dimensions and their IDs. Review the response to find the the dimension IDs you need. Dimension IDs are not available from the Adaptive Planning
web user interface.Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="exportDimensions" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <include versionName="Budget 2004" dimensionIDs="1,2,4,5" dimensionValues="true"/> </call>
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 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, 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) | |||
include element | |||
Tag Name | include | ||
Description | Represents a set of flags indicating what aspects of the 'dimension values' information should be included or excluded from the response. This element is optional: if not present, the default value is blank (or all versions) for versionName/versionID. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
versionName Updated in API v18 | N | Indicates whether the response should exclude dimension values which are unavailable for the requested version name. The default, if the element or its attribute is not present, is to return all dimensions and values. If a version name is specified, dimension values which are unavailable for the specified version will not be returned. If the specified version name is not found, this API returns an error. If both versionName and versionID attributes are passed, the versionID is ignored. <?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <dimensions> <dimension id="6" name="Department" shortName="" autoCreate="0" listDimension="0" keepSorted="0" useOnLevels="1" seqNo="35"> <dimensionValue id="7" name="Engr" description="Engineering" shortName=""> <dimensionValue id="52" name="QA" description="Quality Assurance" shortName="" /> <dimensionValue id="53" name="Dev" description="Development" shortName="" /></dimensionValue> </dimension> <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0" seqNo="21"> <dimensionValue id="32" name="Graduate" description="Graduate degree" shortName=""> <attributes> <attribute attributeId="21" name="Education Type" valueId="197" value="Tech1" /> </attributes> </dimensionValue> <dimensionValue id="33" name="Masters" description="Masters degree" shortName=""> <attributes> <attribute attributeId="21" name="Education Type" valueId="196" value="Management" /> </attributes> </dimensionValue> <dimensionValue id="34" name="Phd" description="Phd" shortName="" /> </dimension> </dimensions> </output> </response> When specifying a version, the call will succeed only if the user has access to the version. | Budget 2004 |
versionID Supported in API v17 + Updated in API v18 | N | Same as versionName (above) except taking a version ID number as a parameter. Indicates whether the response should exclude dimension values which are unavailable for the requested version. The default, if the element or its attribute is not present, is to return all dimensions and values. If a version ID is specified, dimension values which are unavailable for the specified version will not be returned. If the specified version ID is not found, this API returns an error. If both versionName and versionID attributes are passed, the versionID is ignored. When specifying a version, the call will succeed only if the user has access to the version. | 3 |
dimensionIDs Supported in API v17 + | N | A list of ids which will appear in the API response. This filters for a dimension, but not a dimension value. | "1,2,3,14" |
attributes | N | Indicates whether the response should include the attributes in the response for each flat dimension. | false |
inaccessibleValues Supported in API v18 + | N | Indicates whether the response should include values inaccessible to the current user. Defaults to false. Only users with the "Modeling" or "Import to all levels" permissions may set this option to true. | 1 |
dimensionValues Supported in API v22+ | N | Indicates whether the response should include dimension values for each dimension. The default value is true. If set to false, returns filtered dimensions only, and not the dimension values. If dimensionValues is not part of the include element, returns all dimensions and their values. If the include element is not part of the request, all dimensions and their values will return. | false |
displayNameEnabled
Only available in API v30+ for instances that enable display name. | N | displayNameEnabled=true indicates exportDimensions should respect display name properties of code , displayNameType , and description when Enable Display Name is ON for the instance.displayNameEnabled=false indicates the exportDimensions API should continue following the pre-v30 API contract even when Enable Display Name is ON for the instance. The exportDimensions API ignores the display name properties code , displayNameType and description .The default value for displayNameEnabled is "false". | true |
Contents of the Element | |||
(none) | |||
Response Format
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <dimensions> <dimension id="6" name="Department" shortName="" autoCreate="0" listDimension="0" keepSorted="0" useOnLevels="1" seqNo="35"> <dimensionValue id="7" name="Engr" description="Engineering" shortName=""/> <dimensionValue id="52" name="QA" description="Quality Assurance" shortName=""/> <dimensionValue id="53" name="Dev" description="Development" shortName=""/> </dimension> <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0" seqNo="21"> <dimensionValue id="32" name="Graduate" description="Graduate degree" shortName=""> <attributes> <attribute attributeId="21" name="Education Type" valueId="197" value="Tech1" /> </attributes> </dimensionValue> <dimensionValue id="33" name="Masters" description="Masters degree" shortName=""> <attributes> <attribute attributeId="21" name="Education Type" valueId="196" value="Management" /> </attributes> </dimensionValue> <dimensionValue id="34" name="Phd" description="Phd" shortName=""/> </dimension> <dimension id="16" name="Geography" shortName="" autoCreate="0" listDimension="0" keepSorted="0" useOnLevels="0" seqNo="14" property1="Latitude" property2="Longitude"> <dimensionValue id="521" name="United States" description="USA" shortName=""> <dimensionValue id="555" name="Alabama" description="1" shortName=""> <dimensionValue id="579" name="205" description="1" shortName=""> <dimensionValue id="4718" name="35004" description="1" shortName=""> <properties> <property name="Latitude" value="33.606" /> <property name="Longitude" value="-86.502" /> </properties> </dimensionValue> <dimensionValue id="4719" name="35005" description="" shortName=""> <properties> <property name="Latitude" value="33.593" /> <property name="Longitude" value="-86.96" /> </properties> </dimensionValue> <dimensionValue id="5073" name="35006" description="" shortName="" /> <dimensionValue id="5074" name="35007" description="" shortName="" /> </dimensionValue> </dimensionValue> <properties> <property name="Latitude" value="37.0902" /> <property name="Longitude" value="95.7129" /> </properties> </dimensionValue> </dimension> </dimensions> </output> </response>
Dimensions are ordered by name.
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. 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. | |||
output element | |
Tag Name | output |
Attributes of the Element | |
(none) | |
Contents of the Element | |
A single accounts element. This output wrapper is standard on all API responses and encloses the valid output of any successful API call. | |
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 | Represents a single custom dimension being returned in the response to an exportDimensions API call. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | Y | The internal system ID number for the dimension. This can be used to identify dimensions in other API calls, such as exportDimensionFamilies. | 16 |
name | Y | The name of the dimension, as it appears on reports and sheets. | Customer |
code
Only available in API v39+. | N | The name of the dimension, as it appears on reports and sheets. It will only show with API v39+ | Customer |
displayNameType
Only available in API v30+ for instances that enable display name. | N | The internal representation of the selected display name format for values on the Dimension Administration pages.
| NAME |
shortName | N | The short name for the dimension, if any, as entered in Dimension Administration. | cust. |
autoCreate | Y | 1 if the selected dimension has the "Data import automatically creates dimension values" field set, 0 otherwise. | 0 |
listDimension | Y | 1 if the selected dimension is list dimension, 0 otherwise. | 1 |
keepSorted | Y | 1 if the selected dimension is kept sorted, 0 otherwise. | 1 |
useOnLevels | Y | 1 if the selected dimension can be used on levels, 0 otherwise. | 1 |
seqNo Added in API v17 but reserved for future use. | |||
description
Only available in API v30+ for instances that enable display name. | N | The description as entered in Dimension Administration. | |
Contents of the Element | |||
Zero or more dimensionValue elements. Each enclosed dimensionValue elements represents a root dimension value in the dimension, a value that has no parent value. | |||
dimensionValue element | |||
Tag Name | dimensionValue | ||
Description | Represents a single member value of a custom dimension being returned in the response to an exportDimensions API call. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | Y | The internal system ID number for this member value of the dimension. | 34 |
code
Only available in API v30+ for instances that enable display name. | N | The code for the member value of the dimension, if any, as entered in Dimension Administration. | A Corp |
name | Y | The label for the member value of the dimension, as displayed on reports and used in formulas. | A Corp |
displayName
Only available in API v30+ for instances that enable display name. | N | The display name of the member value, as derived from the displayNameType. | A Corp |
shortName | N | The short name for the dimension value, if any, as entered in Dimension Administration | A |
description | N | The description of the dimension value, if any, as entered in Dimension Administration | A Corporation |
Contents of the Element | |||
Zero or more optional dimensionValue elements. Each enclosed dimensionValue element represents a "child dimension value" of this dimension value, whose members implicitly roll up to this value. One optional properties element. | |||
properties element | |||
Tag Name | properties | ||
Description | Optional element that contains property elements. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
(none) | |||
Contents of the Element | |||
Up to five property elements. | |||
property element | |||
Tag Name | property | ||
Description | Specifies a custom property. The property element values only contain numeric characters. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
name | Y | The name of the property. | Latitude |
value | N | The value of the property. | 33.6015 |
Contents of the Element | |||
(none) | |||
attributes element | |||
Tag Name | attributes | ||
Description | Container for one or more dimension attribute elements. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
(none) | |||
Contents of the Element | |||
One or more attribute elements. | |||
attribute element | |||
Tag Name | attribute | ||
Description | Container for one dimension attribute element. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
attributeID | Y | The id of the dimension attribute generated by system. | 20 |
name | Y | The name of the dimension attribute | Education Type |
valueID | Y | The unique id of the dimension attribute value generated by system. | 170 |
value
Supported in API v34 when Effective Display Name setting is ON. | Y | The value of the dimension attribute. | Tech1 |
valueCode
Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34. | N | The attribute value code for this attribute.
For API v32 and API v33, valueCode is only meaningful when:
| Tech1 |
valueName
Only available in API v32 and API v33 for instances that enable display name. Not supported in API v34. | N | The attribute value name for this attribute.
For API v32 and API v33, valueName is only meaningful when:
| Tech1 |
valueDisplayName
Only available in API v32+ for instances that enable display name. | Y | For API v32 and newer, valueDisplayName is meaningful only when:
| Tech1 |
Contents of the Element | |||
(none) | |||