Skip to main content

logoCorrectSize.png

Adaptive Insights LLC.

updateAttributes

Supported in API v20 +

Category

Metadata modification

Description

Update a set of existing attributes and 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" permission and the permission required to administer the attributes being updated.

Best Practice: Invoke exportAttributes to retrieve the Adaptive Insights 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.adaptiveinsights.com/api/v20

updateAttributes.xml contents

Request Format

<?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="stevec@greenco.com" password="changeme" />
   <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

To create a new attribute value, include its parent by its ID. For example, to add 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>

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.

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

 

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

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

Y

The name of the attribute, as it appears on reports and sheets.

Current Assets

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.

1

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

name

Y

The name of the attribute value, as it appears in sheets and reports.

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" 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" listDimensionName="Education" 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> 

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

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

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

seqNo

reserved for future use

     
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.

  • Error: An error was found in the entity 
  • Warning: A warning was found in the entity
  • Created: The entity was created successfully
  • Updated: The entity was updated successfully
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

name

Y

The label for the member value of the attribute as displayed on the attribute administration page.

Available

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.

  • Error: An error was found in the entity 
  • Warning: A warning was found in the entity
  • Created: The entity was created successfully
  • Updated: The entity was updated successfully
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.

 

 

  • Was this article helpful?