exportAttributes
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 attributes 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 all custom attributes (excluding the trading partner sys- tem attribute for consolidation instances), including all of their member values. Member values within an attribute are returned in tree form, with parent members containing their children.
Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="exportAttributes" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> </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 his- tory 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 Supported in API v17 + | |||
Tag Name | include | ||
Description | Represents a set of flags indicating what aspects of the 'attribute values' information should be included or excluded from the response. This element is optional: if not present, all attributes will appear in the response. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
attributeIDs Supported in API v17 + | N | A list of ids which will appear in the API response. This acts like a filter. | "1,2,3,14" |
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. | false |
uncategorized Supported in API v22+ when the instance uses Access Rules for security. | N | Indicates whether the response should include the phantom nodes in the response for each attribute. Defaults to false. The phantom nodes are included in response only when the user has access to them. | false |
displayNameEnabled
Only available in API v30+ for instances that enable display name. | N | displayNameEnabled=true indicates exportAttributes should respect display name properties when Enable Display Name is ON for the instance. displayNameEnabled=false indicates the exportAttributes API should continue following the pre-v30 API contract even when Enable Display Name is ON for the instance. The exportAttributes API ignores the display name properties. 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> <attributes> <attribute id="13" name="AP Eligible" type="account" seqNo="21"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account" seqNo="3"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9" name="Corporate Discount" type="level" seqNo="11"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> <attributeValue id="57" name="Not Available" /> <attributeValue id="55" name="TBD" /> </attribute> <attribute id="10" name="Tax Code" type="level" seqNo="33"> <attributeValue id="146" name="TT-PYT" /> <attributeValue id="145" name="TT-TRE" /> </attribute> <attribute id="16" name="Industry" type="dimension" dimension-id="15" seqNo="43"> <attributeValue id="335" name="Apparel"> <attributeValue id="354" name="Mens Apparel" /> <attributeValue id="355" name="Shoes" /> <attributeValue id="356" name="Womens Apparel" /> </attributeValue> </attribute> </attributes> </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. 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 | |||
Attribute Name | Required? | Value | Example |
(none) | |||
Contents of the Element | |||
A single required attributes element. This output wrapper is standard on all API responses and encloses the valid output of any successful API call. | |||
attributes element | |||
Tag Name | attributes | ||
Description | Container for zero or more attribute elements. Attributes will be ordered so that attributes will be in the following order according to type: 'account', 'level', and 'dimension'. Attributes with the same type will be ordered by name. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
(none) | |||
Contents of the Element | |||
Zero or more attribute elements. | |||
attribute element | |||
Tag Name | attribute | ||
Description | Represents a single attribute being returned in the response to an exportAttributes API call. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | Y | The internal system ID number for the attribute. | 16 |
name | Y | The name of the attribute as it appears on the attribute administration page. | Industry |
displayNameType
Only available in API v30+ for instances that enable display name. | The internal representation of the selected display name format for values on the Attribute Administration pages.
| NAME | |
type | Y | The type of the attribute. This will be 'account' if the attribute is for an account, 'level' if the attri- bute is for a level, or 'dimension' if the attribute is for a dimension. | dimension |
autoCreate Supported in API v20+ | Y | 1 if the selected attribute has "Level/Account/Dimension import automatically creates attribute values" field set, 0 otherwise. | 0 |
keepSorted Supported in API v20+ | Y | "1" indicates values for this attribute are always sorted alphabetically. "0" (or not specified) means attribute values sort based on their position in the request payload. If the XML contains both the parent and at least one sibling of an unlisted hierarchical attribute value, the unlisted value is moved to the end of the listed siblings during the update (in reordering the children of the parent, all listed siblings come first, in the order they are specified in the XML. All unlisted siblings come last, in the order they already have in the system). keepSorted applies to children of each parent attribute value. | 1 |
dimension-id | N | The id of the dimension if the attribute is of type 'dimension'. | 15 |
seqNo Added in API v17 but reserved for future use. | |||
Contents of the Element | |||
Zero or more optional attributeValue elements. Each enclosed attributeValue element represents a "root attribute value" in the attribute, a value which has no parent value. | |||
attributeValue element | |||
Tag Name | attributeValue | ||
Description | Represents a single member value of an attribute being returned in the response to an exportAttributes API call. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | Y | The internal system ID number for this member value of the attribute. | 34 |
code
Only available in API v30+ for instances that enable display name. | N | The code of the member value of the attribute. | Available |
name | Y | The label for the member value of the attribute as displayed on the attribute administration page. | Available |
displayName
Only available in API v30+ for instances that enable display name. | N | The displayName of the member value of the attribute as derived from the displayNameType of the attribute. | Available |
description
Only available in API v30+ for instances that enable display name. | N | The description of the member value of the attribute as displayed on the attribute administration page. | |
Contents of the Element | |||
Zero or more optional attributeValue elements. Each enclosed attributeValue element represents a "child attribute value" of this attribute value, whose members implicitly roll up to this value. | |||