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

updateDimensions

Contains preview content for the upcoming 2018.1 release. 

Supported in API v17 +

Requests are limited to updating a maximum of 10000 dimension values within a single request call of updateDimensions. Please contact Support to have the updateDimensions API enabled for your instance.

Category

Metadata modification

Description

Update a set of existing dimensions and their dimension values. Multiple dimensions and multiple values can be updated in one call. If successful, the API returns details for the dimensions that have just been updated.

Permissions Required To Invoke

Model and permissions on each dimension

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 dimensions being updated.

Best Practice: Invoke exportDimensions to retrieve the Planning dimension IDs needed for your updateDimensions request. No changes should be made to the planning dimensions via the Planning UI or APIs by others before you submit your updateDimensions request.

HTTP Description
Method Post
Content-Type text/xml

 

Curl Example

curl -H "Content-Type: text/xml" -d @C:/temp/updateDimVal.xml -X POST https://api.adaptiveinsights.com/api/v17

updateDimVal.xml contents

<?xml version='1.0' encoding='UTF-8'?>
<call method="updateDimensions" callerName="Steve C">
    <credentials login="stevec@greenco.com" password="password"/>
  <dimensions>
      <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0">
        <dimensionValue id="32" name="Graduate" description="Modified Graduate degree" />
      </dimension>
  </dimensions>
</call>

Request Format

<?xml version='1.0' encoding='UTF-8'?>
<call method="updateDimensions" callerName="Steve C">
    <credentials login="stevec@greenco.com" password="password"/>
  <dimensions>
      <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0">
        <dimensionValue id="32" name="Graduate" description="Graduate degree" shortName="" allVersions="0">
            <attribute name="Education Type" value="Tech1" />
            <version name="Budget 2017" available="1" />
        </dimensionValue>
        <dimensionValue id="33" name="Masters" description="Masters degree" shortName="" allVersions="0">
            <attribute name="Education Type" value="Management" />
            <version name="Budget 2017" available="1" />
        </dimensionValue>
        <dimensionValue id="34" name="Phd" description="Phd" shortName="" />
      </dimension>
  </dimensions>
</call>

The following conditions apply to updateDimensions:

  • Dimensions and dimension values are both identified for update via their internal ID number.

  • Currency, a system dimension, cannot be updated via API.

  • To create new dimensions and dimension values, give them a blank or missing ID property.

    • You can list an existing (non-new) item as 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 Dimension Value

To create a new dimension value, include its parent by its ID. For example, to add a new child value below the Engr value which has id 7, you can use:

<?xml version='1.0' encoding='UTF-8'?>
<call method="updateDimensions" callerName="Steve C">
    <credentials login="stevec@greenco.com" password="password"/>
    <dimensions>
      <dimension id="7">
        <dimensionValue id="" name="Documentation" description="docs" shortName="" >
        </dimensionValue>
      </dimension>
    </dimensions>  
</call>

This method does not change anything about value id 7. It creates a new child named Docs for id 7. All unmentioned children move to the end of the child list. This is the equivalent of "setting the parent" for the new value, but it is accomplished by including that parent as an element. 

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)

 

dimensions element

Tag Name

dimensions

Description

Contains one or more dimensions or dimension values.

Attributes of the Element

Attribute Name

Required?

Value

Example

Contents of the Element

Contains one or more dimensions or dimension values.

 

dimension element

Tag Name

dimension

Description

Specifies a dimension to create.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

The id of the dimension being updated.

34

name

N

The name of the dimension. The name must be unique.

NewDimensionName

shortName

N

Displayable title of the column, as seen on the sheet.

NewDimensionShortName

listDimension

N

"1" means this is a list dimension, "0" (or not specified) means it isn't.

0

useOnLevels

N

"1" means this dimension can be used on levels, "0" (or not specified) means it can't.

0

autoCreate

N

"1" means values for this dimension can be created via the import, "0" (or not specified) means they can't.

0

keepSorted

N

"1" means values for this dimension are always sorted alphabetically, "0" (or not specified) means they can be manually ordered.

0

Contents of the Element

Optional dimensionValue elements.

 

dimensionValue element

Tag Name

dimensionValue

Description

Specifies a dimension value to update.

Attributes of the Element

Attribute Name

Required?

Value

Example

id

Y

The id of the dimension value.

34

name

Y

The name of the dimension value.

NewDimensionValue

shortName

N

The short name of the dimension value.

NewDimensionValueShortName

description

N

The description of the dimension value.

This is a NewDimensionValue

allVersions N

"1" means the dimension value is available in all versions, "0" means it is not.  If allVersions is missing, the default value is 1.

To indicate specific version availability, set allVersions to 0 and provide the dimension value availability for each version.

Example:
Assuming there are versions 2018a, 2018b, 2018c, 2018d

To include a dimension value in only version 2018b:

<dimensionValue .... allVersions="0">
      <version name="2018a" available="0">
      <version name="2018c" available="0">
      <version name="2018d" available="0">

In the example above, if allVersions="1", then the child version elements below it are ignored.

0

Contents of the Element

(none)

 

attribute element

Tag Name

attribute

Description

Container for one dimension attribute element.
Requires a preexisting attribute name and value.

Attributes of the Element

Attribute Name

Required?

Value

Example

name

Y

The name of the dimension attribute

Education Type

value

Y

The value of the dimension attribute.

Tech1

Contents of the Element

(none)

 

version element

Tag Name

version

Description

Specifies the version availability of a dimension value.
Requires a preexisting version.

Attributes of the Element

Attribute Name

Required?

Value

Example

name

Y

The name of the version or folder, as it appears in Version Administration.

Budget 2015

available

Y

If 1 this dimension value is available in this version. 

1

Contents of the Element

One or more version elements for each dimension value.

Response Format

<?xml version='1.0' encoding='UTF-8'?>
<response success="true">
  <messages>
    <message type="INFO">Dimension was saved successfully.</message>
  </messages>
  <output>
    <dimensions>
      <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0" status="nothing changed">
        <dimensionValue id="44" name="Documentation" description="docs" shortName="" status="created">
        </dimensionValue>
      </dimension>
    </dimensions>
  </output>
</response>

dimensions element

Tag Name

dimensions

Description

Contains one or more dimensions or dimension values.

Attributes of the Element

(none)

Contents of the Element

Contains one or more dimensions or dimension values.

 

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

For create, the new ID will be provided.

16

name

Y

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

Customer

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

Contents of the Element

Zero or more dimensionValue elements. Each enclosed dimensionValue element represents a "root dimension value" in the dimension, a value which 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

For create, the new ID will be provided.

16

name

Y

The label for the member value of the dimension, as displayed on reports and used in formulas.

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

status Y

The status of the dimension value following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.

  • Nothing changed: The entity was not changed
  • 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 dimensionValue input. The dimension name ProductsFirst01234567890123456... cannot be more than 64 characters long

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.

 

attribute element

Tag Name

attribute

Description

Container for one dimension attribute element.

Attributes of the Element

Attribute Name

Required?

Value

Example

name

Y

The name of the dimension attribute

Education Type

value

Y

The value of the dimension attribute.

Tech1

status Y

The status of the dimension value following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.

  • Nothing changed: The entity was not changed
  • 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 attribute input.  

Contents of the Element

(none)

 

version element

Tag Name

version

Description

Specifies the version availability of a dimension value.

Attributes of the Element

Attribute Name

Required?

Value

Example

name

Y

The name of the version or folder, as it appears in Version Administration.

Budget 2015

available

Y

If 1 this dimension value is available in this version. 

1

status Y

The status of the dimension value following update. For warning and error, the message element contains the message contents. The status of updated does not return any message contents.

  • Nothing changed: The entity was not changed
  • 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 version input.  

Contents of the Element

One or more version elements for each dimension value.

Error and Warning Message Descriptions 

Type Message Example/Description
Error Internal error. An error occurred in the system.
Error System dimensions cannot be updated via API. Only custom dimensions can be updated.
Error Id "{0}" does not exist. Id "456" does not exist.
The id indicated does not match any id in the system.
Error {0} "{1}" must be an integer value within the range {2} (inclusive) to {3} (inclusive). Dimension id "-3" must be an integer value within range from 1 (inclusive) to 2,147,483,647 (inclusive).
Error The {0} "{1}" cannot be more than {2} characters long. The dimension name "more-than-5-chars" is too long. It cannot be more than X characters in length.
Error The {0} can not be empty. The dimension name can not be empty.
Error A dimension with the name "{0}" already exists. A dimension with the name "Product" already exists.
Error The "{0}" is too long. It cannot be more than {0} characters long. The short name "more-than-5-chars" is too long. It cannot be more than 5 characters in length.
Error A dimension with id "{0}" does not exist. A dimension with id "123" does not exist."
The id indicated for a dimension does not match any id of a dimension in the system.
Error {0} "{1}" must be an integer value within the range {2} (inclusive) to {3} (inclusive). Dimension value id "-3" must be an integer value within range from 1 (inclusive) to 2,147,483,647 (inclusive).
Error The {0} "{1}" cannot be more than {2} characters long. The dimension value name "more-than-5-chars" is too long. It cannot be more than X characters in length.
Error "{0}" is NOT allowed as name. "This" is not allowed as a name.
This is a reserved word that cannot be used as a name.
Error The {0} can not be empty. The dimension value name cannot be empty.
Error A dimension value with the name "{0}" already exists. Dimension value names must be unique within a dimension.
Error A parent with id "{0}" does not exist. A parent with id "123" does not exist."
The id indicated for a parent does not match any id of a parent in the system.
Error Missing Dimension/Dimension value in provided input. No dimension or dimension value was defined.
Error Illegal Input. Input data must be an XML document. The input was not XML. 
Error A dimension value cannot be its own parent. A dimension value referred to itself as a parent.
Error Parent node "{0}" is becoming the child of its current direct/indirect child node "{1}". Parent node "2" is becoming child of its current direct/indirect child node "3".
A parent is set to become the child of itself or one of its children.
Error Invalid {0} "{1}". Invalid dimension name "foo(+)". Invalid dimension name "foo(-)."
+ and - are invalid characters for a dimension name.
Error Invalid {0} "{1}". Invalid dimension value name "foo(+)". Invalid dimension value name "foo(-)."
+ and - are invalid characters for a dimension value name.
Warning Both useOnLevels and listDimension cannot be "1" at the same time. List dimensions cannot have parents.
Warning Invalid "autoCreate" value "x". The value must be "1" or "0". Illegal values for fixed-value properties (e.g. listDimension="1999") leaves the property unchanged and generates a warning.
Warning Invalid "listDimension" value "w". The value must be "1" or "0". Illegal dimension names and dimension value names (length restrictions and character restrictions) are warnings and leaves the element's property unchanged
Warning Invalid "keepSorted" value "z". The value must be "1" or "0". Attempting to change a listDimension or useOnLevels setting to an illegal combination will be a warning and leaves the flag unchanged.
Warning Invalid "useOnLevels" value "y". The value must be "1" or "0". Attempting to create an invalid version visibility combination (stating allVersions=true but then specifying versions) is a warning and will ignore the conflicting "visible" setting, and will respect the allVersions setting.
Warning A list dimension value cannot have parents. List dimensions are not hierarchical and should not have parents.
Warning A dimension value name cannot be the same as its dimension name. Dimension values cannot have the same name as their dimension.
Warning The {0} "{1}" cannot be more than {2} characters long. The dimension value short name "more-than-5-chars" is too long. It cannot be more than 5 characters in length.
Warning The provided dimension attribute {0} is not associated with the dimension {1}. An attribute was provided in the input, but that attribute is not associated with the indicated dimension.

 

  • Was this article helpful?