updateAttributes
Prise en charge dans API v20 et supérieure
Catégorie | Modification des métadonnées |
Description | Mettez à jour un ensemble d'attributs existants, leurs valeurs d'attribut et leurs propriétés. Plusieurs attributs avec plusieurs valeurs d'attribut peuvent être mis à jour en un seul appel. Si l'opération s'effectue avec succès, l'API renvoie le détail des attributs qui ont été mis à jour/créés. Si l'API échoue, une liste complète des erreurs et de leurs causes s'affiche. |
Autorisations requises pour appeler | Rapport modèle |
Paramètres obligatoires à la demande | Identifiants |
La demande de ce mode contient un marqueur d'identifiant pour identifier et autoriser l'utilisateur appelant. L'utilisateur doit avoir le "Modèle" Concept : ensembles d'autorisations et l'autorisation requise pour gérer les attributs en cours de mise à jour.
Une bonne pratique consiste à utiliser exportAttributes pour récupérer les données
Adaptive Planning
Codes d'attribut requis pour votre demande updateAttributes. Faites de votre possible pour réduire le temps entre les appels exportAttributes et updateAttributes.HTTP | Description |
|---|---|
Method | Post |
Content-Type | texte/xml |
Exemple de boucle
curl -H "Content-Type: text/xml" -d @C:/temp/updateAttributes.xml -X POST https://api.adaptiveplanning.com/api/v20
Contenu updateAttributes.xml
Format de demande
Update a set of existing attributes and their attribute values, and their <?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <attributes proceedWithWarnings="0"> <attribute id="13" name="AP Eligible" type="account" keepSorted="1"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> </attribute> </attributes> </call>
Pour les données utiles volumineuses, vous pouvez publier des fichiers XML compressés (zip). Découvrez comment ici.
Les conditions suivantes s'appliquent à updateAttributes :
- Les attributs sont identifiés pour mise à jour via leur numéro d'identification interne.
- Pour créer de nouveaux attributs, attribuez-leur une propriété d'identifiant vide ou manquante.
- Vous pouvez déplacer un élément existant (non nouveau) afin qu'il devienne un enfant d'un nouvel élément. Ainsi, le nouvel élément est créé et l'élément existant est transféré sous ce dernier en tant qu'enfant.
Format de la demande pour la création d'un nouvel attribut
Pour créer un nouvel attribut :
AP Eligible
, laissez le code vide et indiquez son nom et son type.<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="" name="AP Eligible" type="account"> <attributeValue id="" name="No" /> <attributeValue id="" name="Yes"> <attributeValue id="" name="Full" /> <attributeValue id="" name="Partial" /> </attributeValue> </attribute> </attributes> </call>
Demande de création d'un nouvel attribut pour une dimension en liste
Pour créer un nouvel attribut
Education Type
pour une dimension de liste : Education.
Les valeurs d'attribut Technical
et son enfant, Tech1,
ont des identifiants vides, ce qui indique qu'ils sont nouveaux.
<?xml version="1.0" encoding="UTF-8"?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password" /> <attributes> <attribute id="" name="Education Type" type="dimension" listDimensionName="Education" keepSorted="1" importAutoCreateValues="1"> <attributeValue id="" name="Technical" description=""> <attributeValue id="" name="Tech1" description="" /> </attributeValue> <attributeValue id="" name="Management" description="" /> </attribute> </attributes> </call>
Format de la demande pour créer une nouvelle valeur d'attribut
future
en dessous de AP Eligible
attribut avec id 13
, et valeur d'attribut no
avec id 118
, vous pouvez utiliser :<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="13"> <attributeValue id="118" > <attributeValue id="" name="future" /> </attributeValue> </attribute> </attributes> </call> To create a new attribute value, include its parent by its ID. For example, to add a new attribute value
Cette méthode ne modifie rien au niveau de l'attribut
id 13
. Elle crée une nouvelle valeur d'attribut. future
pour l'attribut id 13
et fait de son parent la valeur d'attribut no
. Toutes les valeurs d'attribut non mentionnées de no
Passe à la fin de la liste de valeurs. C'est l'équivalent de "définir le parent" pour la nouvelle valeur d'attribut.Gérer plusieurs changements de nom dans un seul appel updateAttributes
Plusieurs changements de nom de la même entité peuvent avoir lieu dans un système distant entre
updateAttributes
des appels. Les noms des entités sur le système distant peuvent être remplacés par ceux des mêmes identifiants d'entité. Période updateAttributes
Les appels ont lieu après l'échange de noms, les updateAttributes
L'appel gère ces modifications en effectuant le suivi des identifiants dans les changements de nom. L'appel peut également gérer l'introduction d'un nouvel identifiant qui utilise un nom existant.Pour garantir la réussite de chacun des exemples, l'échange complet des identifiants doit avoir lieu avec les valeurs uniques.
Exemple 1 : un échange de noms simple dans le système distant.
To create a new attribute value, include its parent by its ID. For example, to add a new ID Unique Value New Unique Value 1 AA BB 2 BB AA
Exemple 2 : une séquence de 3 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 identifiants | |||
Nom du marqueur | identifiants | ||
Description | Tous les appels d'API doivent contenir un seul élément identifiants pour identifier l'utilisateur qui a appelé l'API. L'appel d'API est ensuite effectué en tant qu'utilisateur ( n'importe quelle piste d'audit ou historique d'actions dans le système indique que cet utilisateur a effectué l'action) et, par conséquent, l'utilisateur doit avoir les autorisations requises pour effectuer l'action afin que l'appel d'API s'appelle réussir. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
se connecter | O | Le nom de connexion de l'utilisateur appelant la méthode API. Cet utilisateur doit avoir les autorisations requises pour appeler la méthode. | sampleuser@company.com |
mot de passe | O | Mot de passe de l'utilisateur appelant la méthode API. | my_password |
paramètres régionaux | N | Indiquez les paramètres régionaux à utiliser pour interpréter les chiffres et les dates entrants, et pour formater les chiffres et les dates sortants (en utilisant le séparateur des milliers, les noms de mois et la mise en forme de date appropriés). Les paramètres régionaux sont également utilisés pour indiquer la langue dans laquelle doivent s'afficher les messages système figurant dans la réponse. Si aucune option n'est indiquée, l'expression en_US (anglais américain) est utilisée. | fr_FR |
instanceCode | N | Si l'utilisateur spécifié dans les identifiants 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 son instance par défaut. Si aucune option n'est indiquée, l'instance par défaut de l'utilisateur sera utilisée. Pour déterminer les codes d'instance disponibles, utilisez l'API exportInstances. | MYINSTANCE1 |
Contenu de l'élément | |||
(aucun) | |||
élément attributs | |||
Nom du marqueur | attributs | ||
Description | Une seule demande d'élément d'attribut est autorisée par données utiles. Il contient un ou plusieurs éléments d'attribut. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
proceedWithWarnings | N | Ne s'applique que lorsque vous redéfinissez le parent de valeurs d'attribut. S'il existe des avertissements et proceedWithWarnings=0, alors attributeValue ne sera pas mis à jour. Définissez proceedWithWarnings=1 pour mettre à jour attributeValue en cas d'avertissement. Ne s'applique qu'aux types = compte et type = périmètre. La redéfinition de la parenté proceedWithWarnings=1 (a) est effectuée même si le marquage de l'attribut de compte/périmètre devient compatible. (b) Tous les marquages d'attributs de compte/périmètre non compatibles seront corrigés en utilisant le marqueur d'attribut parent. proceedWithWarnings=0 si le mappage de l'attribut de compte/périmètre n'est pas compatible avec le mappage d'attributs de compte/périmètre. | 1 |
retenueExistingOrder Disponible dans API v27 et supérieure | N | confidenceExistingOrder="1" indique que l'API updateAttributes doit ignorer l'ordre des éléments dans les données utiles XML et que l'ordre défini existant sera conservé. Rapport de mise à jour des attributs ou de la position du marqueur par rapport aux autres frères/sœurs de la charge de travail XML. L'indicateur retainExistingOrder est ignoré lorsque l'attribut Détail de l'attribut prédéfinie est activé. La valeur par défaut de retainExistingOrder est "1". | 1 |
DisplayNameEnabled
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | displayNameEnabled=1 indique que updateAttributes 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 updateAttributes doit continuer à suivre le contrat de l'API pré-v30, même lorsque l'option Activer le nom d'affichage est activée pour l'instance. L'API updateAttributes ignore les propriétés du nom d'affichage code , displayNameType et description .La valeur par défaut pour displayNameEnabled est "0". | 1 |
Contenu de l'élément | |||
Contient un ou plusieurs éléments d'attribut. | |||
élément d'attribut | |||
Nom du marqueur | attribut | ||
Description | Indique un attribut à créer ou mettre à jour. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
id | O | Numéro d'identifiant système interne de l'attribut. | 16 |
nom
Mis à jour dans l'API v30 | O | Nom de l'attribut, tel qu'il apparaît sur les rapports et les feuilles.
| Actifs circulants |
code
Disponible dans API v39 et supérieure. | N | Le code de l'attribut | Actifs circulants |
displayNameType
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | Contrôle l'affichage des valeurs d'attribut. Les valeurs possibles sont NAME, CODE, NAME_CODE ou CODE_NAME.
Nomme par défaut s'il est laissé vierge ou non renseigné. Cette propriété est uniquement disponible lorsque l'option Activer le nom d'affichage est activée pour l'instance. | "CODE_NAME" |
importAutoCreateValues | N | "1" signifie que les valeurs d'attribut de cet attribut peuvent être créées via l'import, "0" (ou non défini) signifie qu'elles ne peuvent pas. | 1 |
type | N | Indique si l'attribut est un attribut de périmètre, de compte ou de dimension. Obligatoire pour créer de nouveaux attributs qui n'existent pas déjà dans le système. Le type ne peut pas être modifié par une opération de mise à jour. | account |
listDimensionName | N | Indique si la dimension est une dimension de liste plate. Uniquement applicable lorsque type d'attribut = dimension. listDimensionName ne peut pas être modifié par une opération de mise à jour. | couleur |
keepSorted | N | "1" indique que les valeurs de cet attribut sont toujours triées par ordre alphabétique. "0" (ou non spécifié) signifie que les valeurs d'attribut sont triées en fonction de leur position dans les données utiles de la demande. La valeur par défaut est "0" uniquement dans l'opération de création lorsqu'aucune valeur n'est fournie. Si XML contient à la fois le parent et au moins un frère d'une valeur d'attribut hiérarchique non répertoriée, la valeur non répertoriée est déplacée à la fin des frères/sœurs répertoriés pendant la mise à jour (dans le réordre des enfants du parent, tous les frères/sœurs répertoriés apparaissent en premier, dans L'ordre dans lequel ils sont indiqués dans le fichier XML. Tous les frères/sœurs non répertoriés apparaissent en dernier, dans l'ordre qu'ils ont déjà dans le système). ainsi que les valeurs d'attributs prédéfinies s'appliquent aux enfants de chaque valeur d'attribut parent. Tout changement apporté aux composants d'un nom d'affichage est susceptible de modifier l'ordre de tri des éléments, lorsque l'option Conserver le tri est activée. | 1 |
shortName
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | Le nom abrégé de l'attribut. Le nombre maximum de caractères est 64.
Uniquement disponible lorsque l'option Activer le nom d'affichage est activée pour l'instance. | Actifs |
description
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | Description de l'attribut. Le nombre maximum de caractères est 2048.
Valeur par défaut : vide Cette propriété est uniquement disponible lorsque l'option Activer le nom d'affichage est activée pour l'instance. | Actifs |
Contenu de l'élément | |||
Un ou plusieurs éléments attributeValue. | |||
élément attributeValue | |||
Nom du marqueur | attributeValue | ||
Description | Indique les valeurs d'attribut à créer ou mettre à jour. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
id | N | Identifie la valeur de l'attribut. Si ce champ est laissé vide, cela indique qu'une nouvelle valeur d'attribut est créée par la demande. | 24 |
code
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | Le code unique de la valeur de l'attribut.
| oui |
nom
Mis à jour dans l'API v30 | O | Nom de la valeur d'attribut, tel qu'il apparaît dans les feuilles et les rapports. Lorsque l'option Activer le nom d'affichage est activée pour une instance avec API v30 ou ultérieure, 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. Noms illégaux de valeurs d'attribut : ces noms se terminent par (+) ou (-) | oui |
description | N | Description textuelle de la valeur de l'attribut. Valeur par défaut : vide La valeur par défaut est uniquement utilisée dans l'opération de création lorsqu'aucune valeur n'est fournie. | |
Contenu de l'élément | |||
Peut contenir un autre attributeValue. | |||
Format de la réponse
<?xml version="1.0" encoding="UTF-8"?> <response success="true"> <messages> <message type="INFO">Attributes were saved successfully.</message> </messages> <output> <attributes> <attribute id="13" name="AP Eligible" type="account"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9" name="Corporate Discount" type="level"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> <attributeValue id="57" name="Not Available" /> <attributeValue id="55" name="TBD" /> </attribute> <attribute id="10" name="Tax Code" type="level"> <attributeValue id="146" name="TT-PYT" /> <attributeValue id="145" name="TT-TRE" /> </attribute> <attribute id="16" name="Industry" type="dimension" listDimensionName="Education"> <attributeValue id="335" name="Apparel"> <attributeValue id="354" name="Mens Apparel" /> <attributeValue id="355" name="Shoes" /> <attributeValue id="356" name="Womens Apparel" /> </attributeValue> </attribute> </attributes> </output> </response>
élément de sortie | |
Nom du marqueur | sortie |
Attributs de l'élément | |
(aucun) | |
Contenu de l'élément | |
Un seul élément attributs obligatoires. Ce filtre de sortie est standard sur toutes les réponses d'API et contient la sortie valide de tout appel d'API réussi. | |
élément attributs | |||
Nom du marqueur | attributs | ||
Description | Conteneur pour zéro ou plusieurs éléments d'attribut. Les marqueurs sont placés en fonction de la demande de saisie. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
proceedWithWarnings | N | La valeur proceedWithWarnings est fournie dans la demande API. | 1 |
retenueExistingOrder | N | updateAttributes=0 met à jour l'ordre de tri en fonction du contenu des données utiles XML. updateAttributes=1 conservent l'ordre de tri existant. | 1 |
displayNameEnabled
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | displayNameEnabled=1 indique que updateAttributes doivent 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 updateAttributes doit continuer à suivre le contrat API pré-2021.42, même lorsque l'option Activer le nom d'affichage est activée pour l'instance. L'API updateAttributes ignore les propriétés du nom d'affichage code , displayNameType et description .La prise en charge de displayNameEnabled a commencé en 2021.42. La valeur par défaut pour displayNameEnabled est "0". | 1 |
Contenu de l'élément | |||
Un ou plusieurs éléments d'attribut. | |||
élément d'attribut | |||||
Nom du marqueur | attribut | ||||
Description | Représente un attribut unique renvoyé en réponse à un appel d'API updateAttributes. | ||||
Attributs de l'élément | |||||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple | ||
id | O | Numéro d'identifiant système interne de l'attribut. | 16 | ||
nom | O | Nom de l'attribut, tel qu'il apparaît sur les rapports et les feuilles. | Actifs circulants | ||
code
Disponible dans API v39 et supérieure. | O | Le code de l'attribut. | Actifs circulants | ||
shortName | Le nom abrégé de l'attribut. Le nombre maximum de caractères est 2048. | Actifs | |||
displayNameType
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | Contrôle l'affichage des valeurs d'attribut. Les valeurs possibles sont NAME, CODE, NAME_CODE ou CODE_NAME.
Nomme par défaut s'il est laissé vierge ou non renseigné. Cette propriété est uniquement disponible lorsque l'option Activer le nom d'affichage est activée pour l'instance. | CODE_NAME | ||
importAutoCreateValues | N | "1" signifie que les valeurs d'attribut de cet attribut peuvent être créées via l'import, "0" (ou non défini) signifie qu'elles ne peuvent pas. | 1 | ||
type | O | Type de l'attribut. Ce sera 'compte' si l'attribut est pour un compte, 'périmètre' si l'attribut est pour un périmètre, ou 'dimension' si l'attribut est pour une dimension. | account | ||
listDimensionName | N | Le nom de la dimension en liste si l'attribut est de type 'dimension'. | Education | ||
description | N | Description du texte de l'attribut, le cas échéant, tel que saisi dans l'administration des attributs. | Total des actifs circulants | ||
keepSorted | O | "1" indique que les valeurs de cet attribut sont toujours triées par ordre alphabétique. "0" (ou non spécifié) signifie que les valeurs d'attribut sont triées en fonction de leur position dans les données utiles de la demande. Si XML contient à la fois le parent et au moins un frère d'une valeur d'attribut hiérarchique non répertoriée, la valeur non répertoriée est déplacée à la fin des frères/sœurs répertoriés pendant la mise à jour (dans le réordre des enfants du parent, tous les frères/sœurs répertoriés apparaissent en premier, dans L'ordre dans lequel ils sont indiqués dans le fichier XML. Tous les frères/sœurs non répertoriés apparaissent en dernier, dans l'ordre qu'ils ont déjà dans le système). ainsi que les valeurs d'attributs prédéfinies s'appliquent aux enfants de chaque valeur d'attribut parent. | 1 | ||
statut | O | Statut de la valeur d'attribut après mise à jour. Pour les avertissements et les erreurs, l'élément de message contient le contenu du message. Le statut de mise à jour ne renvoie aucun contenu de message.
| Mis à jour | ||
message | N | Le message d'erreur pour l'entrée de l'attribut. | L'attribut Secteur d'activité est en double dans les données utiles ou existe déjà dans le système avec l'identifiant 8. | ||
Contenu de l'élément | |||||
Aucun ou plusieurs éléments attributeValue facultatifs. Chaque élément attributeValue inclus représente une "valeur d'attribut racine" dans l'attribut, une valeur qui n'a pas de valeur parent. | |||||
élément attributeValue | |||
Nom du marqueur | attributeValue | ||
Description | Représente la valeur d'un membre unique d'un attribut renvoyé en réponse à un appel d'API updateAttributes. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
id | O | Le numéro d'identifiant système interne associé à cette valeur de membre de l'attribut. | 34 |
code
Uniquement disponible dans API v30 et supérieure pour les instances qui activent le nom d'affichage. | N | Le code unique de la valeur de l'attribut. | Disponible |
nom | O | Libellé de la valeur de membre de l'attribut tel qu'il s'affiche sur la page d'administration des attributs. | Disponible |
shortName | N | Le nom abrégé de la valeur de l'attribut. | Moy. |
description | N | Description de la valeur de l'attribut. Valeur par défaut : vide La valeur par défaut est uniquement utilisée dans l'opération de création lorsqu'aucune valeur n'est fournie. | |
propogateToDescendants | N | Indique si les modifications sont consécutives jusqu'aux enfants de ce périmètre. 0 pour non, 1 pour oui. | 0 |
statut | O | Le statut de l'attribut après mise à jour. Pour les avertissements et les erreurs, l'élément de message contient le contenu du message. Le statut de mise à jour ne renvoie aucun contenu de message.
| mis à jour |
message | N | Message d'erreur pour une entrée attributeValue non valide. | |
Contenu de l'élément | |||
Aucun ou plusieurs éléments attributeValue facultatifs. Chaque élément attributeValue inclus représente une "valeur d'attribut enfant" de cette valeur d'attribut, dont les membres s'agrègent implicitement à cette valeur. | |||