Passer au contenu principal
Documentation
Documentation
Adaptive Planning
Dernière mise à jour : 2025-10-03
updateDimensions

updateDimensions

Pris en charge dans l'API v17 +
Pour un seul appel de demande de
updateDimensions
 Les demandes sont limitées à la mise à jour d’un maximum de 10 000 valeurs de dimension dans une dimension hiérarchique, ou de 40 000 valeurs de dimension dans une dimension plate. Ces limites ne s’appliquent pas à la création de nouvelles valeurs de dimension dans une demande.
Catégorie
Modification de métadonnées
Description
Mettez à jour un ensemble de dimensions existantes et leurs valeurs de dimension. Plusieurs dimensions et plusieurs valeurs peuvent être mises à jour en un seul appel. En cas d’une mise à jour réussie, l’API renvoie les détails des dimensions qui viennent d’être mises à jour.
Autorisations obligatoires pour pouvoir être appelées
Modèle et autorisations pour chaque dimension
Paramètres requis sur demande
Identifiants
La demande de cette méthode contient un marqueur d’identifiants pour désigner et autoriser l’utilisateur auteur de l’appel. L'utilisateur doit avoir le « Modèle » Concept : ensembles d’autorisations et l’autorisation requise pour administrer les dimensions mises à jour.
Meilleure pratique : Invoquer exportDimensions pour récupérer les identifiants de dimension Planning nécessaires pour votre demande de mise à jour de Dimensions. Aucune modification ne doit être apportée aux dimensions Planning via l'interface utilisateur ou les API Planning par d'autres personnes avant que vous soumettiez votre demande updateDimensions.
HTTP
Description
Method
Post
Content-Type
text/xml

Exemple de boucle


curl -H "Content-Type: text/xml" -d @C:/temp/updateDimVal.xml -X POST https://api.adaptiveplanning.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>

Joindre un exemple de URL de fichier XML



curl -i -X POST -H "Content-Type: multipart/form-data" -F "request=<C:/temp/requestCreateNewDimVal.xml" -F "content=@C:/temp/createNewDimVal.xml" https://api.adaptiveplanning.com/api/v17
requestCreateNewDimVal.xml content


<?xml version='1.0' encoding='UTF-8'?>
<call method="updateDimensions" callerName="Steve C">
 <credentials login="sampleuser@company.com" password="my_password"/>
</call>
createNewDimVal.xml


<?xml version='1.0' encoding='UTF-8'?>
<dimensions>
  <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0">
    <dimensionValue id="" name="Graduate" description="Graduate degree" />
  </dimension>
</dimensions>
Pour les charges utiles importantes, vous pouvez publier des fichiers XML compressés (zIP). Voir : Mise à jour en bloc des métadonnées.

Format de demande


<?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>
Les conditions suivantes s'appliquent à updateDimensions :
  • Les dimensions et les valeurs de dimension sont désignées aux fins de mise à jour par leur numéro d’identifiant interne.
  • La devise, une dimension système, ne peut pas être mise à jour via l'API.
  • Pour créer de nouvelles dimensions et valeurs de dimension, attribuez-leur une propriété d’identifiant vide ou manquante.
    • Dans une dimension existante, vous pouvez déplacer une dimensionValue existante (non nouvelle) sous une nouvelle dimensionValue. Cela crée la nouvelle dimensionValue et déplace la dimensionValue existante sous celle-ci en tant qu’enfant.
  • Toutes les valeurs de dimension créées pour les dimensions fixes sont visibles dans toutes les versions de plan par défaut. Pour préciser la visibilité, vous devez la mentionner explicitement à l’aide de l’un des éléments suivants :
    • Le
      allVersions
       attribut dans
      dimensionValue
       marqueur
    • Ou en fournissant un enfant
      version
       marqueurs sous
      dimensionValue
       pour offrir une visibilité personnalisée
    updateDimensions met uniquement à jour la disponibilité des versions pour les versions de plan. Vous ne pouvez pas mettre à jour la disponibilité des versions pour les versions des chiffres réels, même lorsque allVersions = 1.

Format de demande pour la création d'une nouvelle valeur de dimension

Pour créer une nouvelle valeur de dimension, incluez son parent par son identifiant. Par exemple, pour ajouter une nouvelle valeur enfant sous la
Engr
 valeur qui a
id 7
, vous pouvez utiliser :

<?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>
Cette méthode ne change rien à la valeur
id 7
. Il crée un nouvel enfant nommé
Docs
 pour
id 7
. Tous les enfants non précisés sont déplacés vers la fin de la liste des enfants. Cela équivaut à "définir le parent" pour la nouvelle valeur, mais il est effectué en incluant ce parent comme élément.

Format de demande pour la création d'une nouvelle valeur de dimension avec code et nom

Pour créer une nouvelle valeur de dimension, incluez son parent par son identifiant. Par exemple, pour ajouter une nouvelle valeur enfant sous la valeur Eng dont l’identifiant est 7, vous pouvez utiliser :
<?xml version="1.0" encoding="UTF-8"?>
<call method="updateDimensions" callerName="Steve C">
<credentials login="sampleuser@company.com" password="my_pwd" />
<dimensions displayNameEnabled="1">
   <dimension id="7">
      <dimensionValue id="" code ="Doc" name="Documentation" description="docs" shortName="">
         <properties>
            <property name="OwnerID" value="58371998" />      
         </properties>
      </dimensionValue>
   </dimension>
</dimensions>
</call>

Format d’entrée 1 : la charge utile inclut l’arborescence de la dimension entière

L’API updateDimensions fonctionne mieux lorsqu’un demandeur souhaite fournir le nouvel état de l’arborescence sans se soucier des changements.
L’API updateDimensions figure sur les changements apportés à la structure de dimension et uniquement les valeurs de dimension/dimension qui ont été modifiées ou qui sont nouvelles sont mises à jour. Le
dimensions
 l'élément ne contient qu'un enfant direct
dimension
 ou
dimensionValue
 élément.
<?xml version="1.0" encoding="UTF-8"?>
<call method="updateDimensions" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd" />
<dimensions>
   <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>

Format d'entrée 2 : Structure de sous-arborescence des dimensions

Ce format prend en charge les cas d’utilisation lorsque les changements sont limités à une seule partie de la structure d’arborescence de la dimension.
L’API updateDimensions figure sur les changements apportés à la structure de dimension et uniquement les valeurs de dimension/dimension qui ont été modifiées ou qui sont nouvelles sont mises à jour. Le
dimensions
 l'élément ne contient qu'un enfant direct
dimensionValue
 élément.
Par exemple, les changements concernent l’Alabama :
<?xml version="1.0" encoding="UTF-8"?>
<call method="updateDimensions" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd" />
<dimensions>
   <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>
   </dimensionValue>
</dimensions>
</call>
Pour les dimensions fixes, vous devez fournir le parent
dimension
 marqueur sous
dimensions
 marqueur, suivi d’une ou de plusieurs valeurs de dimension.
dimensions
 l'élément ne contient qu'un enfant direct
dimension
 élément.
<?xml version="1.0" encoding="UTF-8"?>
<call method="updateDimensions" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd" />
<dimensions>
   <dimension id="16" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0">
      <dimensionValue id="521" name="Graduate" shortName="" description="Graduate degree" />
      <dimensionValue id="522" name="Masters" shortName="" description="Masters degree" />
   </dimension>
</dimensions>
</call>

Format d'entrée 3 : mettre à jour une valeur de dimension unique

Ce format prend en charge les cas d’utilisation lorsque les changements se limitent à une seule valeur de dimension.
Le
dimensions
 l'élément ne contient qu'un enfant direct
dimensionValue
 élément.
Utilisez uniquement le format d'entrée 3 lors de la mise à jour d'une valeur de dimension unique. Le format d’entrée 3 n’est pas le format privilégié pour la mise à jour de plusieurs valeurs de dimension. Vous ne pouvez pas créer de nouvelles dimensions/valeurs de dimension avec ce format. Utilisez le format d’entrée 2 pour ajouter de nouvelles dimensions/valeurs de dimension.
<?xml version="1.0" encoding="UTF-8"?>
<call method="updateDimensions" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd" />
<dimensions>
   <dimensionValue id="555" name="Alabama" description="1" shortName=""/>
</dimensions>
</call>

Traitement de plusieurs changements dans un seul appel updateDimensions

Plusieurs renouvellements de noms de la même entité peuvent avoir lieu dans un système distant entre
updateDimensions
 les appels. Les noms des entités du système distant peuvent être échangés pour les mêmes identifiants d’entité. Quand
updateDimensions
 les appels ont lieu après l’échange de noms, les
updateDimensions
 appel gère ces changements en suivant les identifiants pour tous les changements de nom. L’appel peut également traiter l’introduction d’un nouvel identifiant qui utilise un nom existant.
Pour que chacun des exemples réussisse, l’échange complet des identifiants doit avoir lieu avec des valeurs uniques.
Exemple 1 : un simple échange de noms dans le système distant.

ID     Unique Value   New Unique Value
1      AA             BB
2      BB             AA
Exemple 2 : une séquence de trois noms dans le système distant.

ID     Unique Value   New Unique Value
1      AA             BB
2      BB             CC
3      CC             AA
Exemple 3 : une nouvelle entité utilisant une valeur unique existante.

ID     Unique Value   New Unique Value
4                     AA
1      AA             BB
2      BB             Old BB
élément de données d'identification
Nom du marqueur
données d'identification
Description
Tous les appels d’API doivent contenir un élément d’identification unique pour identifier l’utilisateur qui invoque l’API. L’appel d’API est alors effectué en tant que cet utilisateur (toute piste d’audit ou tout historique des actions dans le système indiquera que cet utilisateur a effectué l’action). Par conséquent, l’utilisateur doit disposer des autorisations requises pour effectuer l’action afin que l’appel d’API puisse être exécuté réussir.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
login
Y
Le nom de connexion de l’utilisateur qui invoque la méthode API. Cet utilisateur doit disposer des autorisations requises pour invoquer la méthode.
sampleuser@company.com
mot de passe
Y
Le mot de passe de l’utilisateur qui invoque la méthode API.
my_password
locale
N
Indiquez les paramètres régionaux à utiliser pour interpréter les numéros et les dates entrants et pour mettre en forme les numéros et les dates sortants (à l’aide du séparateur des milliers, des noms de mois et du format de date appropriés). Les paramètres régionaux sont également utilisés pour préciser la langue dans laquelle tous les messages de système de la réponse doivent être affichés. Si cette valeur n’est pas précisée, la valeur en_US (rubrique en anglais américain) est utilisée.
fr_FR
instanceCode
N
Si l’utilisateur indiqué dans les données d’identification a accès à plusieurs instances de Adaptive Planning, cet attribut peut être utilisé pour indiquer que l’utilisateur a l’intention d’accéder à une instance autre que celle par défaut. Si elle n’est pas précisée, l’instance par défaut de l’utilisateur sera utilisée. Pour déterminer les codes d’instances disponibles, utilisez l’API exportInstances.
MYINSTANCE1
Contenu de l'élément
(aucun)
élément de dimensions
Nom du marqueur
dimensions
Description
Contient une ou plusieurs dimensions ou valeurs de dimension.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
retainExistingOrder
Disponible dans l'API v27+
N
MaintainExistingOrder="1" indique que l’API updateDimensions doit ignorer l’ordre des éléments dans les données utiles XML, et que l’ordre défini existant sera conservé.
MaintainExistingOrder="0" indique que l’API updateDimensions doit mettre à jour l’ordre des éléments en fonction de la position du marqueur par rapport aux autres enfants de mêmes parents dans les données utiles XML.
L'indicateur MaintainExistingOrder est ignoré lorsque l'indicateur MaintainSorted est activé pour Dimension.
La valeur par défaut pour MaintainExistingOrder est « 1 ».
1
displayNameEnabled
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
N
displayNameEnabled=1 indique que updateDimensions doit respecter les propriétés du nom d'affichage de
code
,
displayNameType
, et
description
 lorsque l’option Activer le nom d’affichage est ACTIVÉE pour l’instance.
displayNameEnabled=0 indique que l’API updateDimensions doit continuer à suivre le contrat de l’API antérieure à la version 30, même lorsque l’option Activer le nom d’affichage est ACTIVÉE pour l’instance. L'API updateDimensions ignore les propriétés du nom d'affichage
code
,
displayNameType
 Et
description
.
La valeur par défaut pour displayNameEnabled est « 0 ».
Contenu de l'élément
Contient une ou plusieurs dimensions ou valeurs de dimension.
élément de dimension
Nom du marqueur
dimension
Description
Indique une dimension à créer.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
identifiant
Y
Identifiant de la dimension mise à jour.
34
nom
N
Le nom de la dimension. Le nom doit être unique.
NewDimensionName
code
Disponible dans l’API v39+.
Le code de la dimension. Le code doit être unique.
NewDimensionCode
shortName
N
Titre affiché de la colonne, comme on le voit sur la feuille.
NewDimensionShortName
listDimension
N
"1" signifie qu'il s'agit d'une dimension de liste, "0" (ou non précisé) signifie qu'elle n'en est pas une.
0
useOnLevels
N
"1" signifie que cette dimension peut être utilisée dans des niveaux, "0" (ou non précisée) signifie qu’elle ne peut pas être utilisée.
0
autoCreate
N
"1" signifie que les valeurs pour cette dimension peuvent être créées via l'importation, "0" (ou non indiqué) signifie qu'elles ne peuvent pas.
0
keepSorted
N
« 1 » signifie que les valeurs de cette dimension sont toujours triées par ordre alphabétique; « 0 » (ou non précisé) signifie qu’elles peuvent être triées manuellement.
Toute modification apportée aux composantes d’un nom d’affichage modifie l’ordre de tri des éléments, même si l’option Conserver le tri est activée.
0
displayNameType
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
N
Contrôle l'affichage des valeurs de dimension. Les valeurs possibles sont NAME, Code, NAME_Code ou Code_NAME.
La valeur par défaut est NAME lorsqu’elle est laissée en blanc ou non fournie.
Cette propriété n’est disponible que lorsque l’option Activer le nom d’affichage est activée pour l’instance.
"CODE_NAME"
description
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
N
Description de la dimension.
Cette propriété n’est disponible que lorsque l’option Activer le nom d’affichage est activée pour l’instance.
« le descendants sur la dimension »
propriété1, propriété2,...
N
Les propriétés de la dimension, le cas échéant, telles qu’elles sont entrées dans l’administration des dimensions. Chaque dimension peut avoir jusqu’à cinq propriétés.
"Latitude"
Contenu de l'élément
Éléments dimensionValue facultatifs.
Élément dimensionValue
Nom du marqueur
dimensionValue
Description
Indique une valeur de dimension à mettre à jour.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
identifiant
Y
L'identifiant de la valeur de dimension.
34
code
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
N
Code unique de la valeur de dimension.
NewDimensionValue
nom
Y
Le nom de la valeur de dimension. Lorsque l’option Activer le nom d’affichage est activée pour une instance avec l’API v30 ou une version plus récente, le nom autorise les valeurs en double. Lorsque l'option Activer le nom d'affichage est désactivée pour une instance, le code n'est pas disponible et le nom doit être unique.
Caractères de nouvelle ligne (
&#10;)
 trouvés entre les mots sont remplacés par une seule espace pendant le traitement des données utiles.
Les caractères de nouvelle ligne trouvés au début ou à la fin du nom sont également remplacés par des espaces uniques. Ces espaces ne s’affichent pas dans l’interface utilisateur en raison de la réduction des espaces blancs pendant le traitement des données utiles.
NewDimensionValue
shortName
N
Nom abrégé de la valeur de dimension.
NewDimensionValueShortName
description
N
Description de la valeur de dimension.
Ceci est une NewDimensionValue
allVersions
N
« 1 » signifie que la valeur de dimension est disponible dans toutes les versions du plan, « 0 » signifie qu’elle ne l’est pas. Si allVersions est manquant, la valeur par défaut est 1.
updateDimensions met uniquement à jour la disponibilité des versions pour les versions de plan. Vous ne pouvez pas mettre à jour la disponibilité des versions pour les versions des chiffres réels, même lorsque allVersions = 1.
Pour indiquer la disponibilité d’une version précise, définissez allVersions avec la valeur 0 et indiquez la disponibilité de la valeur de dimension pour chaque version.
Exemple : en supposant qu’il existe des versions 2018a, 2018b, 2018c, 2018d Pour inclure une valeur de dimension uniquement dans la version 2018b :
<dimensionValue.... allVersions="0"> <version name="2018a" disponible="0"> <version name="2018c" disponible="0"> <version name="2018d" disponible="0" >
Dans l’exemple ci-dessus, si allVersions="1", les éléments de version enfants inférieurs sont ignorés.
0
Contenu de l'élément
Peut contenir l’élément facultatif de propriétés.
élément d'attribut
Nom du marqueur
attribut
Description
Conteneur pour un élément d'attribut de dimension. Nécessite un nom et une valeur d'attribut préexistants.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
nom
Y
Nom de l'attribut de dimension
Emplacement
valeur
mis à jour dans l’API v34
Y
La valeur de l'attribut de dimension.
Si l’importation de dimension crée automatiquement des valeurs d’attribut est activée dans l’interface utilisateur de l’administrateur des attributs de dimensions, toute valeur d’attribut qui n’existe pas déjà devient une nouvelle valeur d’attribut à la dimension racine.
Pour les API v32 et v33, cet attribut n’est significatif que lorsque le paramètre Nom d’affichage est désactivé pour l’instance.
Pour l’API v34 et les versions plus récentes :
  • Pris en charge lorsque le paramètre Nom d'affichage en vigueur est ACTIVÉ.
  • La présence de valueCode et de valueName générera une erreur.
  • Lorsque l’importation de dimension crée automatiquement des valeurs d’attributs est activée dans l’interface utilisateur de l’administrateur des attributs, la chaîne de valeurs devient le code et le nom si la valeur n’existe pas déjà.
Définissez value="" pour supprimer le marquage de cet attribut.
SFO
valueCode
Disponible uniquement dans API v32 et API v33 pour les instances qui activent le nom d’affichage.
Non pris en charge dans l'API v34.
Y
Le code de valeur d'attribut pour cet attribut.
L’entrée valueCode n’est significative que lorsque DisplayNameEnabled=1 et que le paramètre Nom d’affichage est ACTIVÉ pour l’instance dans l’API v32 et l’API v33.
Définissez valueCode="" pour supprimer le marquage de cet attribut.
SFO
valueName
Disponible uniquement dans API v32 et API v33 pour les instances qui activent le nom d’affichage.
Non pris en charge dans l'API v34.
N
Le nom d'une valeur d'attribut nouvellement créée automatiquement.
L’attribut est significatif uniquement quand :
  • valueCode contient une valeur d'attribut qui n'existe pas.
  • Le paramètre Nom d’affichage est ACTIVÉ pour l’instance.
  • displayNameEnabled=1
  • En appel d’API v32 et d’API v33.
valueName est ignoré lorsque valueCode contient une valeur d'attribut existante.
San Francisco
Contenu de l'élément
(aucun)
élément de version
Nom du marqueur
version
Description
Indique la disponibilité de la version du plan pour une valeur de dimension. Nécessite une version de plan préexistante. La disponibilité de la version ne peut pas être modifiée pour les versions virtuelles, masquées, réelles, verrouillées ou archivées.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
nom
Y
Le nom de la version, tel qu’il apparaît dans l’administration des versions.
Budget 2015
disponible
Y
Si 1, cette valeur de dimension est disponible dans cette version.
1
Contenu de l'élément
Un ou plusieurs éléments de version pour chaque valeur de dimension.
élément de propriétés
Pris en charge dans l'API v22
Nom du marqueur
propriétés
Description
Élément facultatif contenant des éléments de propriété.
Attributs de l'élément
(aucun)
Contenu de l'élément
Contient jusqu’à cinq éléments de propriété.
élément de propriété
Pris en charge dans l'API v22
Nom du marqueur
propriété
Description
Indique une propriété personnalisée à mettre à jour. Les valeurs d'éléments de propriété peuvent uniquement contenir des caractères numériques.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
nom
Y
Le nom de la propriété.
Latitude
valeur
Y
La valeur de la propriété. Une valeur vide va effacer la valeur de la propriété pour la valeur de la dimension.
33.6015
Contenu de l'élément
(aucun)

Format de réponse


<?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>
élément de dimensions
Nom du marqueur
dimensions
Description
Contient une ou plusieurs dimensions ou valeurs de dimension.
Attributs de l'élément
(aucun)
Contenu de l'élément
Contient une ou plusieurs dimensions ou valeurs de dimension.
retainExistingOrder
N
Si la valeur est 0, l’API updateDimensions doit mettre à jour l’ordre de tri en fonction du contenu des données utiles XML.
Si la valeur est 1, l’API updateDimensions doit conserver l’ordre de tri existant.
1
displayNameEnabled
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
displayNameEnabled=1 indique que updateDimensions doit respecter les propriétés du nom d'affichage de
code
,
displayNameType
, et
description
 lorsque l’option Activer le nom d’affichage est ACTIVÉE pour l’instance.
afficherNameEnabled=0 indique que l’API updateDimensions doit continuer à suivre le contrat de l’API avant la version 2021.42, même lorsque l’option Activer le nom d’affichage est ACTIVÉE pour l’instance. L'API updateDimensions ignore les propriétés du nom d'affichage
code
,
displayNameType
 Et
description
.
La prise en charge de afficherNameEnabled commence en 2021.42. La valeur par défaut pour displayNameEnabled est « 0 ».
1
élément de dimension
Nom du marqueur
dimension
Description
Représente une dimension personnalisée unique renvoyée en réponse à un appel d'API exportDimensions.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
identifiant
Y
Pour créer, le nouvel identifiant sera fourni.
16
nom
Y
Le nom de la dimension, tel qu’il apparaît sur les rapports et les feuilles.
Client
code
Disponible dans l’API v39+.
N
Le code de la dimension.
Client
shortName
N
Nom abrégé de la dimension, le cas échéant, tel qu’il est entré dans l’administration des dimensions
client.
autoCreate
Y
1 si la dimension sélectionnée comporte l’ensemble de champs " Importation de données crée automatiquement des valeurs de dimension "; 0 dans le cas contraire.
0
listDimension
Y
1 si la dimension sélectionnée est une dimension de liste; 0 dans le cas contraire.
1
keepSorted
Y
1 si la dimension sélectionnée est conservée et triée, 0 dans le cas contraire.
1
useOnLevels
Y
1 si la dimension sélectionnée peut être utilisée dans les niveaux, 0 dans le cas contraire.
1
displayNameType
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
N
Contrôle l'affichage des valeurs de dimension. Les valeurs possibles sont NAME, Code, NAME_Code ou Code_NAME.
La valeur par défaut est NAME lorsqu’elle est laissée en blanc ou non fournie.
Cette propriété n’est disponible que lorsque l’option Activer le nom d’affichage est activée pour l’instance.
CODE_NAME
description
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
N
Description de la dimension.
propriété1,propriété2,...
N
Les propriétés personnalisées de la dimension.
Contenu de l'élément
Zéro ou plusieurs éléments dimensionValue. Chaque élément dimensionValue inclus représente une "valeur de dimension racine" dans la dimension, une valeur qui n'a pas de valeur parent.
Élément dimensionValue
Nom du marqueur
dimensionValue
Description
Représente une valeur de membre unique d'une dimension personnalisée renvoyée en réponse à un appel d'API exportDimensions.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
identifiant
Y
Pour créer, le nouvel identifiant sera fourni.
16
code
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage.
N
Code unique de la valeur de dimension.
Une entreprise
nom
Y
Étiquette de la valeur membre de la dimension, telle qu'elle est affichée dans les rapports et utilisée dans les formules.
Une entreprise
shortName
N
Nom abrégé de la valeur de dimension, le cas échéant, tel qu'il est entré dans l'administration des dimensions
A
description
N
Description de la valeur de dimension, le cas échéant, telle qu’elle est entrée dans l’administration des dimensions
Une société
status
Y
Le statut de la valeur de dimension suivant la mise à jour. Pour les avertissements et les erreurs, l’élément de message contient le contenu du message. Le statut Mis à jour ne renvoie aucun contenu de message.
  • Erreur : une erreur a été repérée dans l'entité
  • Avertissement : un avertissement a été repéré dans l'entité
  • Créé : l'entité a été créée avec succès
  • Mis à jour : l'entité a été mise à jour
mis à jour
message
N
Le message d'erreur pour une entrée dimensionValue non valide.
Le nom de la dimension ProduitsFirst01234567890123456... ne doit pas dépasser 64 caractères
Contenu de l'élément
Zéro ou plusieurs éléments dimensionValue facultatifs. Chaque élément dimensionValue inclus représente une "valeur de dimension enfant" de cette valeur de dimension, dont les membres sont implicitement regroupés dans cette valeur.
élément d'attribut
Nom du marqueur
attribut
Description
Conteneur pour un élément d'attribut de dimension.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
nom
Y
Nom de l'attribut de dimension
Emplacement
valeur
mis à jour dans l’API v32
Y
La valeur de l'attribut de dimension.
Pour l’API v32 et les versions plus récentes, cet attribut n’a de sens que lorsque le paramètre Nom d’affichage est désactivé pour l’instance.
San Francisco
valueCode
Disponible uniquement dans l’API v32+ pour les instances qui activent le nom d’affichage.
Y
Le code de valeur d'attribut pour cet attribut.
Pour l’API v32 et les versions plus récentes, valueCode n’a de sens que lorsque :
  • Le paramètre Nom d’affichage est ACTIVÉ pour l’instance.
  • displayNameEnabled=1
SFO
valueName
Disponible uniquement dans l’API v32+ pour les instances qui activent le nom d’affichage.
N
Le nom d'une valeur d'attribut nouvellement créée automatiquement.
L’attribut est significatif uniquement quand :
  • valueCode contient une valeur d'attribut qui n'existe pas.
  • Le paramètre Nom d’affichage est ACTIVÉ pour l’instance.
  • displayNameEnabled=1value
Le nom est ignoré lorsque valueCode contient une valeur d'attribut existante.
San Francisco
status
Y
Le statut de la valeur de dimension suivant la mise à jour. Pour les avertissements et les erreurs, l’élément de message contient le contenu du message. Le statut Mis à jour ne renvoie aucun contenu de message.
  • Erreur : une erreur a été repérée dans l'entité
  • Avertissement : un avertissement a été repéré dans l'entité
  • Créé : l'entité a été créée avec succès
  • Mis à jour : l'entité a été mise à jour
mis à jour
message
N
Le message d'erreur pour une entrée d'attribut non valide.
Contenu de l'élément
(aucun)
élément de version
Nom du marqueur
version
Description
Indique la disponibilité de la version du plan pour une valeur de dimension.
Attributs de l'élément
Nom de l’attribut
Obligatoire?
Valeur
Exemple
nom
Y
Le nom de la version, tel qu’il apparaît dans l’administration des versions.
Budget 2015
disponible
Y
Si 1, cette valeur de dimension est disponible dans cette version du plan.
1
status
Y
Le statut de la valeur de dimension suivant la mise à jour. Pour les avertissements et les erreurs, l’élément de message contient le contenu du message. Le statut Mis à jour ne renvoie aucun contenu de message.
  • Erreur : une erreur a été repérée dans l'entité
  • Avertissement : un avertissement a été repéré dans l'entité
  • Créé : l'entité a été créée avec succès
  • Mis à jour : l'entité a été mise à jour
mis à jour
message
N
Le message d’erreur pour une entrée de version non valide.
Contenu de l'élément
Un ou plusieurs éléments de version pour chaque valeur de dimension.
élément de propriétés
Nom du marqueur
propriétés
Description
Contient jusqu’à cinq éléments de propriété.
Attributs de l'élément
(aucun)
Contenu de l'élément
Contient jusqu’à cinq éléments de propriété.
élément de propriété
Nom du marqueur
propriété
Description
Indique une propriété personnalisée à mettre à jour.
Attributs de l'élément
Nom de l’attribut
Valeur
Exemple
nom
Le nom de la propriété.
Latitude
valeur
La valeur de la propriété. Une valeur vide va effacer la valeur de la propriété pour la valeur de la dimension.
33.6015
Statut
Le statut de la propriété est mis à jour après. Pour les erreurs, l’élément de message contient le contenu du message d’erreur. Le statut Mis à jour ne renvoie aucun contenu de message.
  • Erreur : une erreur a été repérée dans l'entité
  • Créé : l'entité a été créée avec succès
  • Mis à jour : l'entité a été mise à jour
  • Rien de changé : un statut vide signifie que rien n’a été changé pour l’entité.
Message
Le message d'erreur pour une entrée de propriété non valide.
Le marqueur de propriété requiert un attribut de nom.