updateDimensions
Supported in API v17 +
For a single request call of updatedimensions requests are limited to updating a maximum of 10000 dimension values in a hierarchical dimension, or 40000 dimension values in a flat dimension. These limits do not apply to creation of new dimension values within a request.
|
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="sampleuser@company.com" password="my_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>
For large payloads, you can post compressed XML files (zipped). Find out how here.
Request Format
<?xml version='1.0' encoding='UTF-8'?>
<call method="updateDimensions" callerName="Steve C">
<credentials login="sampleuser@company.com" password="my_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>
<dimension id="16" name="Geography" 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="33" shortName="">
<properties>
<property name="Latitude" value="33.6015" />
<property name="Longitude" value="86.4895" />
</properties>
</dimensionValue>
<dimensionValue id="4719" name="35005" description="" shortName="" />
</dimensionValue>
<properties>
<property name="Latitude" value="" />
<property name="Longitude" value="86.9023" />
</properties>
</dimensionValue>
</dimensionValue>
</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.
-
-
All dimension values created for flat dimensions are visible in all versions by default. To specify visibility you must explicitly mention it using either:
-
The
allVersionsattribute in thedimensionValuetag -
Or by providing child
versiontags underdimensionValueto provide custom visibility
-
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="sampleuser@company.com" password="my_password"/>
<dimensions>
<dimension id="7">
<dimensionValue id="" name="Documentation" description="docs" shortName="" >
<properties>
<property name="OwnerID" value="58371998"/>
</properties>
</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 Insights, 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: <dimensionValue .... allVersions="0"> In the example above, if allVersions="1", then the child version elements below it are ignored. |
0 |
|
Contents of the Element |
|||
|
Can contain the optional properties element. |
|||
|
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 updated in API v18 |
Y |
The value of the dimension attribute. If "Dimension import automatically creates attribute values" is enabled in the dimension attribute administrator UI, any attribute value that does not already exist becomes a new attribute value at the root level. |
Tech1 |
|
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 |
|
Contents of the Element |
|||
|
One or more version elements for each dimension value. |
|||
|
properties element Supported in API v22 |
|
|
Tag Name |
properties |
|
Description |
Optional element that contains property elements. |
|
Attributes of the Element |
|
|
(none) |
|
|
Contents of the Element |
|
|
Contains up to five property elements. |
|
|
property element Supported in API v22 |
|||
|
Tag Name |
property |
||
|
Description |
Specifies a custom property to update. The property element values can only contain numeric characters. | ||
|
Attributes of the Element |
|||
|
Attribute Name |
Required? |
Value |
Example |
|
name |
Y |
The name of the property. |
Latitude |
|
value |
Y |
The value of the property. An empty value will erase the property value for the dimension value. |
33.6015 |
|
Contents of the Element |
|||
|
(none) |
|||
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="">
<dimensionValue id="44" name="Documentation" description="docs" shortName="" status="created">
</dimensionValue>
</dimension>
<dimension id="16" name="Geography" shortName="" autoCreate="0" listDimension="0" keepSorted="0" useOnLevels="0" property1="Latitude" property2="Longitude" status="">
<dimensionValue id="521" name="United States" shortName="" description="USA" status="">
<dimensionValue id="555" name="Alabama" shortName="" description="1" status="">
<dimensionValue id="579" name="205" shortName="" description="1" status="">
<dimensionValue id="4718" name="35004" shortName="" description="33" status="">
<properties>
<property name="Latitude" value="33.6015" status="created" />
<property name="Longitude" value="86.4895" status="" />
</properties>
</dimensionValue>
<dimensionValue id="4719" name="35005" shortName="" description="" status="" />
</dimensionValue>
<properties>
<property name="Latitude" value="" status="deleted" />
<property name="Longitude" value="86.9023" status="updated" />
</properties>
</dimensionValue>
</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.
|
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.
|
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.
|
updated |
| message | N | The error message for an invalid version input. | |
|
Contents of the Element |
|||
|
One or more version elements for each dimension value. |
|||
|
properties element |
|
|
Tag Name |
properties |
|
Description |
Contains up to five property elements. |
|
Attributes of the Element |
|
|
(none) |
|
|
Contents of the Element |
|
|
Contains up to five property elements. |
|
|
property element |
|||
|
Tag Name |
property |
||
|
Description |
Specifies a custom property to update. | ||
|
Attributes of the Element |
|||
|
Attribute Name |
Value
|
Example |
|
|
name |
The name of the property. |
Latitude |
|
|
value |
The value of the property. An empty value will erase the property value for the dimension value. |
33.6015 |
|
|
Status |
The status of the property following update. For error, the message element contains the error message contents. The status of updated does not return any message contents.
|
||
|
Message |
The error message for an invalid property input. |
Property tag requires a name attribute. |
|
Error and Warning Message Descriptions