updateAttributes
Supported in API v20 +
Category | Metadata modification |
Description | Update a set of existing attributes, their attribute values, and their properties. Multiple attributes with multiple attribute values can be updated in one call. If successful, the API returns details for the attributes that were updated/created. If the API fails, a comprehensive list of errors and their causes returns. |
Permissions Required To Invoke | Model |
Parameters Required On Request | Credentials |
This method's request contains a credentials tag to identify and authorize the calling user. User must have the "Model" Concept: Permission Sets and the permission required to administer the attributes being updated.
Best Practice: Invoke exportAttributes to retrieve the
Adaptive Planning
attribute IDs needed for your updateAttributes request. Do your best to minimize the time between exportAttributes calls and updateAttributes calls.HTTP | Description |
|---|---|
Method | Post |
Content-Type | text/xml |
Curl Example
curl -H "Content-Type: text/xml" -d @C:/temp/updateAttributes.xml -X POST https://api.adaptiveplanning.com/api/v20
updateAttributes.xml contents
Request Format
Update a set of existing attributes and their attribute values, and their <?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <attributes proceedWithWarnings="0"> <attribute id="13" name="AP Eligible" type="account" keepSorted="1"> <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"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> </attribute> </attributes> </call>
For large payloads, you can post compressed XML files (zipped). Find out how, here.
The following conditions apply to updateAttributes:
- Attributes are identified for update via their internal ID number.
- To create new attributes, give them a blank or missing ID property.
- You can move an existing (non-new) item so that it becomes a child of a new item. Doing so creates the new item and moves the existing item under it as a child.
Request Format for Creating a New Attribute
To create a new attribute,
AP Eligible
, leave id blank and provide its name and type.<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="" name="AP Eligible" type="account"> <attributeValue id="" name="No" /> <attributeValue id="" name="Yes"> <attributeValue id="" name="Full" /> <attributeValue id="" name="Partial" /> </attributeValue> </attribute> </attributes> </call>
Request for Creating a New Attribute for a List Dimension
To create a new attribute
Education Type
for a list dimension, Education.
The attribute values Technical
and its child, Tech1,
have blank ids, indicating they are new.
<?xml version="1.0" encoding="UTF-8"?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password" /> <attributes> <attribute id="" name="Education Type" type="dimension" listDimensionName="Education" keepSorted="1" importAutoCreateValues="1"> <attributeValue id="" name="Technical" description=""> <attributeValue id="" name="Tech1" description="" /> </attributeValue> <attributeValue id="" name="Management" description="" /> </attribute> </attributes> </call>
Request Format for Creating a New Attribute Value
future
below the AP Eligible
attribute with id 13
, and attribute value no
with id 118
, you can use:<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="13"> <attributeValue id="118" > <attributeValue id="" name="future" /> </attributeValue> </attribute> </attributes> </call> To create a new attribute value, include its parent by its ID. For example, to add a new attribute value
This method does not change anything about attribute
id 13
. It creates a new attribute value future
for attribute id 13
and makes its parent the attribute value no
. All unmentioned attribute values of no
move to the end of the value list. This is the equivalent of "setting the parent" for the new attribute value.Handling Multiple Renames in a Single updateAttributes Call
Multiple renames of the same entity can take place in a remote system between
updateAttributes
calls. The names of entities on the remote system can swap for the same entity IDs. When updateAttributes
calls take place after the name swap, the updateAttributes
call manages these changes by tracking the IDs across name changes. The call can also handle the introduction of a new ID that uses an existing name.For each of the examples to succeed, the full swap of IDs must take place with the unique values.
Example 1: A simple name swap in the remote system.
To create a new attribute value, include its parent by its ID. For example, to add a new ID Unique Value New Unique Value 1 AA BB 2 BB AA
Example 2: A sequence of 3 renames in the remote system.
ID Unique Value New Unique Value 1 AA BB 2 BB CC 3 CC AA
Example 3: A new entity using an existing unique value.
ID Unique Value New Unique Value 4 AA 1 AA BB 2 BB Old BB
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) | |||
attributes element | |||
Tag Name | attributes | ||
Description | Only 1 attributes element request is allowed per payload. It contains one or more attribute elements. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
proceedWithWarnings | N | Only applies when re-parenting attribute values. If there are warnings, and proceedWithWarnings=0, then attributeValue will not be updated. Set proceedWithWarnings=1 to update the attributeValue when there are warnings. Only applies to type=account and type=level. ProceedWithWarnings=1 (a) re-parentage is performed even when account/level attribute tagging will become incompatible . (b) All incompatible account/level attribute tagging will be corrected by using the parent's attribute tagging. ProceedWithWarnings=0 errors out if attribute value re-parentage would result in account/level attribute mapping becoming incompatible. | 1 |
retainExistingOrder Available in API v27+ | N | retainExistingOrder="1" indicates updateAttributes API should ignore the order of elements in the XML payload and existing defined order will be retained. retainExistingOrder="0" indicates updateAttributes API should update the order of elements based on the tag position relative to other siblings in the XML payload. The retainExistingOrder flag is ignored when attribute has keepSorted flag enabled. The default value for retainExistingOrder is "1". | 1 |
DisplayNameEnabled
Only available in API v30+ for instances that enable display name. | N | displayNameEnabled=1 indicates updateAttribues should respect display name properties of code , displayNameType , and description when Enable Display Name is ON for the instance.displayNameEnabled=0 indicates the updateAttributes API should continue following the pre-v30 API contract even when Enable Display Name is ON for the instance. The updateAttributes API ignores the display name properties code , displayNameType and description .The default value for displayNameEnabled is "0". | 1 |
Contents of the Element | |||
Contains one or more attribute elements. | |||
attribute element | |||
Tag Name | attribute | ||
Description | Specifies an attribute to create or update. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | Y | The internal system ID number for the attribute. | 16 |
name
Updated in API v30 | Y | The name of the attribute, as it appears on reports and sheets.
| Current Assets |
code
Available in API v39+. | N | The code of the attribute | Current Assets |
displayNameType
Only available in API v30+ for instances that enable display name. | N | Controls the display of attribute values. The possible values are NAME, CODE, NAME_CODE or CODE_NAME.
Defaults to NAME when left blank or not provided. This property is only available when Enable Display Name is ON for the instance. | "CODE_NAME" |
importAutoCreateValues | N | "1" means attribute values for this attribute can be created via import, "0" (or not specified) means they can't. | 1 |
type | N | Indicates whether the attribute is a level, account, or dimension attribute. Required for creating new attributes that don't already exist in the system. Type cannot be changed by an update operation. | account |
listDimensionName | N | Indicates if the dimension is a flat list dimension. Only applicable when attribute type=dimension. listDimensionName cannot be changed by an update operation. | color |
keepSorted | N | "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. Defaults to "0" only in the create operation when no value is provided. 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. Any changes to the components of a display name could alter the sort order of elements, when Keep Sorted is enabled. | 1 |
shortName
Only available in API v30+ for instances that enable display name. | N | The short name of the attribute. Max character length is 64.
Only available when Enable Display Name is ON for the instance. | Assets |
description
Only available in API v30+ for instances that enable display name. | N | The description of the attribute. Max character length is 2048.
Default value: empty This property is only available when Enable Display Name is ON for the instance. | Assets |
Contents of the Element | |||
One or more attributeValue elements. | |||
attributeValue element | |||
Tag Name | attributeValue | ||
Description | Specifies attribute values to be created or updated. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
id | N | Identifies the attribute value. If left blank, indicates a new attribute value being created by the request. | 24 |
code
Only available in API v30+ for instances that enable display name. | N | The unique code of the attribute value.
| yes |
name
Updated in API v30 | Y | The name of the attribute value, as it appears in sheets and reports. When Enable Display Name is ON for an instance with API v30 or higher, name allows duplicate values. When Enable Display Name is OFF for an instance, code is not available and name must be unique. Illegal attribute value names: this names ending with (+) or (-) | yes |
description | N | The textual description of the attribute value. Default value: empty Default value is only used in create operation when no value is provided. | |
Contents of the Element | |||
Can contain another attributeValue. | |||
Response Format
<?xml version="1.0" encoding="UTF-8"?> <response success="true"> <messages> <message type="INFO">Attributes were saved successfully.</message> </messages> <output> <attributes> <attribute id="13" name="AP Eligible" type="account"> <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"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9" name="Corporate Discount" type="level"> <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"> <attributeValue id="146" name="TT-PYT" /> <attributeValue id="145" name="TT-TRE" /> </attribute> <attribute id="16" name="Industry" type="dimension" listDimensionName="Education"> <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>
output element | |
Tag Name | output |
Attributes of the Element | |
(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. Tags are placed in order based on the input request. | ||
Attributes of the Element | |||
Attribute Name | Required? | Value | Example |
proceedWithWarnings | N | proceedWithWarnings value provided in API request. | 1 |
retainExistingOrder | N | updateAttributes=0 updates sort order based on the XML payload content. updateAttributes=1 retain existing sort order. | 1 |
displayNameEnabled
Only available in API v30+ for instances that enable display name. | N | displayNameEnabled=1 indicates updateAttributes should respect display name properties of code , displayNameType , and description when Enable Display Name is ON for the instance.displayNameEnabled=0 indicates the updateAttribues API should continue following the pre-2021.42 API contract even when Enable Display Name is ON for the instance. The updateAttribues API ignores the display name properties code , displayNameType and description .Support for displayNameEnabled began in 2021.42. The default value for displayNameEnabled is "0". | 1 |
Contents of the Element | |||
One or more attribute elements. | |||
attribute element | |||||
Tag Name | attribute | ||||
Description | Represents a single attribute being returned in the response to an updateAttributes 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 reports and sheets. | Current Assets | ||
code
Available in API v39+. | Y | The code of the attribute. | Current Assets | ||
shortName | The short name for the attribute. Max character length is 2048. | Assets | |||
displayNameType
Only available in API v30+ for instances that enable display name. | N | Controls the display of attribute values. The possible values are NAME, CODE, NAME_CODE or CODE_NAME.
Defaults to NAME when left blank or not provided. This property is only available when Enable Display Name is ON for the instance. | CODE_NAME | ||
importAutoCreateValues | N | "1" means attribute values for this attribute can be created via import, "0" (or not specified) means they can't. | 1 | ||
type | Y | The type of the attribute. This will be 'account' if the attribute is for an account, 'level' if the attribute is for a level, or 'dimension' if the attribute is for a dimension. | account | ||
listDimensionName | N | The name of the list dimension if the attribute is of type 'dimension'. | Education | ||
description | N | The textual description of the attribute, if any, as entered in Attribute Administration | Total current assets | ||
keepSorted | 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 | ||
status | Y | The status of the attribute value following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.
| Updated | ||
message | N | The error message for the attribute input. | The attribute Industry is either duplicated in the payload or already exists in the system with ID 8 | ||
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 updateAttributes 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 unique code of the attribute value. | Available |
name | Y | The label for the member value of the attribute as displayed on the attribute administration page. | Available |
shortName | N | The short name of the attribute value. | Avl |
description | N | The description of the attribute value. Default value: empty Default value is only used in create operation when no value is provided. | |
propogateToDescendants | N | Indicates if changes propagate to the children of this level. 0 for no, 1 for yes. | 0 |
status | Y | The status of the attribute following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.
| updated |
message | N | The error message for an invalid attributeValue input. | |
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. | |||