updateDimensions

Dernière mise à jour
Enregistrer en tant que PDF

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.
- Within an existing dimension, you can shift an existing (non-new) dimensionValue under a new dimensionValue. Doing so creates the new dimensionValue and moves the existing dimensionValue 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 allVersions attribute in the dimensionValue tag
- Or by providing child version tags under dimensionValue to 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 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
Can contain the optional properties element.

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

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

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. Error: An error was found in the entity Created: The entity was created successfully Updated: The entity was updated successfully Nothing Changed: An empty status means nothing has been changed for the entity.
Message	The error message for an invalid property input.		Property tag requires a name attribute.

Error and Warning Message Descriptions

Type	Message	Exemple/Description
Erreur	Erreur interne :	Une erreur s’est produite dans le système.
Erreur	Les dimensions de système ne peuvent pas être mises à jour via API.	Seules les dimensions personnalisées peuvent être mises à jour.
Erreur	L’Id "{0}" n’existe pas.	L’Id "456" n’existe pas. L’Id indiqué ne correspond à aucun id dans le système.
Erreur	{0} "{1}" doit être un nombre entier compris entre {2} (inclus) et {3} (inclus).	L’id de dimension "-3" doit être un nombre entier compris entre 1 (inclus) et 2,147,483,647 (inclus).
Erreur	La longueur de {0} "{1}" ne peut pas dépasser {2} caractères.	Le nom de dimension "supérieur à 5 caractères" est trop long. La longueur ne peut pas dépasser X caractères.
Erreur	Le {0} ne peut être vide.	Le nom de la dimension doit être renseigné.
Erreur	Une dimension avec le nom "{0}" existe déjà.	Une dimension avec le nom "Produit" existe déjà.
Erreur	Le "{0}" est trop long. La longueur ne peut pas dépasser {0} caractères.	Le nom abrégé "supérieur à 5 caractères" est trop long. La longueur ne peut pas dépasser 5 caractères.
Erreur	Aucune dimension avec identifiant "{0}" n’existe.	Aucune dimension avec l’identifiant 123 n’existe." L’identifiant indiqué pour une dimension ne correspond à aucun identifiant de dimension dans le système.
Erreur	{0} "{1}" doit être un nombre entier compris entre {2} (inclus) et {3} (inclus).	L’identifiant de valeur de dimension "-3" doit être un nombre entier compris entre 1 (inclus) et 2,147,483,647 (inclus).
Erreur	La longueur de {0} "{1}" ne peut pas dépasser {2} caractères.	Le nom de valeur de dimension "supérieur à 5 caractères" est trop long. La longueur ne peut pas dépasser X caractères.
Erreur	"{0}" n’est PAS autorisé comme nom.	"Ceci" n’est pas autorisé comme nom. C’est un mot réservé qui ne peut pas être utilisé comme nom. S’applique uniquement aux noms de valeurs de dimension.
Erreur	Le {0} ne peut être vide.	Le nom de la valeur de dimension doit être renseigné.
Erreur	Une valeur de dimension avec le nom "{0}" existe déjà.	Les noms de valeur de dimension doivent être uniques dans une dimension.
Erreur	Une valeur de dimension avec le nom "{0}" existe déjà dans l’instance de planification pour la valeur de dimension ID {0}.	Une valeur de dimension avec le nom "Ordinateurs" existe déjà dans l’instance de planification pour la valeur de dimension ID 317.
Erreur	Une valeur de dimension avec le nom "{0}" existe dans la charge utile {0} fois.	Une valeur de dimension avec le nom "Ordinateurs" existe dans la charge utile 2 fois.
Erreur	Dimension/Valeur de dimension manquante dans l’entrée fournie.	Aucune dimension ou valeur de dimension n’a été définie.
Erreur	Saisie illégale. Les données entrées doivent être un document XML.	La saisie ne correspondait pas XML.
Erreur	Une valeur de dimension ne peut pas être son propre élément parent.	Une valeur de dimension faisant référence à sa propre valeur en tant qu’élément parent.
Erreur	Le nœud parent "{0}" devient l’enfant de son nœud enfant direct/indirect actuel "{1}".	Le nœud parent "2" devient l’enfant de son nœud enfant direct/indirect actuel "3". Un élément parent est amené à être son propre élément enfant ou l’un de ses éléments enfants.
Erreur	Non valide {0} "{1}".	Nom de dimension non valide "foo(+)". Nom de dimension non valide "foo(-)." + et - sont des caractères non valides pour un nom de dimension.
Erreur	Non valide {0} "{1}".	Nom de valeur de dimension non valide "foo(+)". Nom de valeur de dimension non valide "foo(-)." + et - sont des caractères non valides pour un nom de valeur de dimension.
Attention	useOnLevels et listDimension ne peuvent être simultanément "1".	Les dimensions de liste ne peuvent pas avoir de parents.
Attention	Valeur "autoCreate" non valide "x". La valeur doit être "1" ou "0".	Des valeurs illégales pour des propriétés de valeur fixe (par exemple, listDimension="1999") ne modifient pas la propriété et génèrent un message d’avertissement.
Attention	Valeur "DimensionListe" non valide "w". La valeur doit être "1" ou "0".	Les noms illégaux de dimension et de valeur de dimension (restrictions de longueur et restrictions de caractère) correspondent à des avertissements et ne modifient pas la propriété d’élément
Attention	Valeur "keepSorted" non valide "z". La valeur doit être "1" ou "0".	Si vous essayez de remplacer un paramètre listDimension ou useOnLevels par une combinaison illégale, un message d’avertissement est généré et le code reste inchangé.
Attention	Valeur "useOnLevels" non valide "y". La valeur doit être "1" ou "0".	Toute tentative de création d’une association non valide version/visibilité (indiquant toutesVersions=vrai, mais en spécifiant les versions) correspond à un avertissement et l’option "visible" en conflit sera ignorée et le paramètre toutesVersions sera pris en compte.
Attention	Une valeur de dimension liste ne peut pas avoir de parents.	Les dimensions Liste ne sont pas hiérarchiques et ne doivent pas avoir de parents.
Attention	Le nom d’une valeur de dimension ne peut pas être identique à celui de sa dimension.	Des valeurs de dimension ne peuvent pas avoir le même nom que leur dimension.
Attention	La longueur de {0} "{1}" ne peut pas dépasser {2} caractères.	Le nom abrégé de valeur de dimension "supérieur à 5 caractères" est trop long. La longueur ne peut pas dépasser 5 caractères.
Attention	L’attribut de dimension {0} indiqué n’est pas associé à la dimension {1}.	Un attribut a été fourni dans l’entrée, mais cet attribut n’est pas associé à la dimension indiquée.