updateAttributes
Pris en charge dans l'API v20 +
Catégorie
| Modification de 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. En cas de réussite, l’API renvoie les détails des attributs qui ont été mis à jour/créés. Si l’API échoue, une liste complète des erreurs et de leurs causes est retournée. |
Autorisations obligatoires pour pouvoir être appelées
| Modèle |
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 attributs mis à jour.
Bonne pratique : appelez exportAttributes pour récupérer
Adaptive Planning
Identifiants d'attributs nécessaires pour votre demande de mise à jour des attributs. Faites de votre mieux pour réduire le temps entre les appels exportAttributes et les appels 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 de 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 charges utiles importantes, vous pouvez publier des fichiers XML compressés (zIP). Découvrez comment ici.
Les conditions suivantes s'appliquent à updateAttributes :
- Les attributs sont repérés aux fins de mise à jour par leur numéro d’identifiant interne.
- Pour créer de nouveaux attributs, attribuez-leur une propriété d’ID vide ou manquante.
- Vous pouvez déplacer un élément existant (qui n’est pas un nouveau) pour qu’il devienne un enfant d’un nouvel élément. Cela crée le nouvel élément et déplace l’élément existant en tant qu’enfant.
Format de demande pour la création d'un nouvel attribut
Pour créer un nouvel attribut,
AP Eligible
, laissez l’identifiant 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 de 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 en blanc, indiquant 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 demande pour la création d'une nouvelle valeur d'attribut
future
sous la section 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 change rien à l'attribut
id 13
. Une nouvelle valeur d'attribut est créée future
pour l'attribut id 13
et définit son parent comme valeur d’attribut no
. Toutes les valeurs d'attribut non mentionnées de no
passer à la fin de la liste de valeurs. Cela équivaut à "définir le parent" pour la nouvelle valeur d'attribut.Traitement de plusieurs renouvellements en un seul appel updateAttributes
Plusieurs renouvellements de noms de la même entité peuvent avoir lieu dans un système distant entre
updateAttributes
les appels. Les noms des entités du système distant peuvent être échangés pour les mêmes identifiants d’entité. Quand updateAttributes
les appels ont lieu après l’échange de noms, les updateAttributes
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.
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 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
|
ouvrir une session | 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 |
paramètres régionaux | 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 préciser 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 d'attributs
| |||
Nom du marqueur
| attributs | ||
Description
| Une seule demande d'élément d'attributs est autorisée par charge utile. Elle contient un ou plusieurs éléments d'attribut. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
poursuivreAvertirs | N | S'applique uniquement lorsque vous redéfinissez la parenté des valeurs d’attribut. S'il y a des avertissements, et proceedWithWarnings=0, attributeValue ne sera pas mis à jour. Définissez proceedWithWarnings=1 pour mettre à jour l’attribut attributeValue en cas d’avertissements. S’applique uniquement à type=account et type=niveau. La redéfinition de la parenté proceedWithWarnings=1 (a) est effectuée même lorsque le marquage des attributs de compte/niveau devient incompatible. (b) Tous les marqueurs d’attributs de compte/niveau incompatibles seront corrigés à l’aide du marquage d’attributs du parent. Les erreurs proceedWithWarnings=0 si la redéfinition de la parenté de la valeur d’attribut rendrait le mappage de comptes et d’attributs de niveau incompatible. | 1 |
MaintainExistingOrder Disponible dans l'API v27+ | N | MaintainExistingOrder="1" indique que l’API de updateAttributes 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 updateAttributes 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 l'attribut. 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 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 antérieure à la version 30, 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
|
identifiant | Y | Le numéro d’identifiant de système interne pour l’attribut. | 16 |
nom
Mis à jour dans l'API v30 | Y | Le nom de l’attribut, tel qu’il apparaît sur les rapports et les feuilles.
| Actifs à court terme |
code
Disponible dans l’API v39+. | N | Le code de l'attribut | Actifs à court terme |
displayNameType
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage. | N | Contrôle l'affichage des valeurs d'attributs. 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" |
importAutoCreateValues | N | "1" signifie que les valeurs d’attribut pour cet attribut peuvent être créées via l’importation, "0" (ou non indiqué) signifie qu’elles ne peuvent pas. | 1 |
type | N | Indique si l’attribut est un attribut de niveau, de compte ou de dimension. Obligatoire pour la création de nouveaux attributs qui n’existent pas encore dans le système. Le type ne peut pas être modifié par une opération de mise à jour. | compte |
listDimensionName | N | Indique si la dimension est une dimension de liste fixe. Uniquement applicable lorsque l’attribut type=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 précisé) signifie que les valeurs d’attribut sont triées en fonction de leur position dans la charge utile 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 le XML contient à la fois le parent et au moins un apparenté d’une valeur d’attribut hiérarchique non répertoriée, la valeur non répertoriée est déplacée à la fin des semblables répertoriés pendant la mise à jour (en réorganisant les enfants du parent, tous les enfants de mêmes parents inscrits sur la liste viennent en premier, dans l’ordre dans lequel ils sont précisés dans le XML. Tous les congés non répertoriés viennent en dernier, dans l’ordre qu’ils ont déjà dans le système). garderSorted s’applique aux enfants de chaque valeur d’attribut parent. Tout changement apporté aux composantes d’un nom d’affichage peut modifier l’ordre de tri des éléments lorsque l’option Conserver le tri est activée. | 1 |
shortName
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage. | N | Le nom abrégé de l'attribut. Le nombre maximum de caractères est de 64.
Disponible uniquement lorsque l’option Activer le nom d’affichage est ACTIVÉE pour l’instance. | Actifs |
description
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage. | N | La description de l'attribut. Le nombre maximum de caractères est 2 048.
Valeur par défaut : vide Cette propriété n’est disponible que 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
|
identifiant | N | Repère la valeur de l'attribut. Si ce champ est laissé en blanc, cela indique qu’une nouvelle valeur d’attribut est créée par la demande. | 24 |
code
Disponible uniquement dans l’API v30+ 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 | Y | Le nom de la valeur de l’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 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. Noms de valeurs d’attributs illégals : 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 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 d'attributs obligatoires. Ce filtre de sortie est standard sur toutes les réponses d’API et enveloppe la sortie valide de tout appel d’API réussi. | |
élément d'attributs
| |||
Nom du marqueur
| attributs | ||
Description
| Conteneur pour zéro ou plusieurs éléments d'attribut. Les marqueurs sont placés en ordre en fonction de la demande d’entrée. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
poursuivreAvertirs | N | Valeur proceedWithWarnings fournie dans la demande d'API. | 1 |
MaintainExistingOrder | N | updateAttributes=0 met à jour l’ordre de tri en fonction du contenu des données utiles XML. updateAttributes=1 conserve l’ordre de tri existant. | 1 |
displayNameEnabled
Disponible uniquement dans l’API v30+ 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.afficherNameEnabled=0 indique que l’API updateAttribues 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 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
| ||
identifiant | Y | Le numéro d’identifiant de système interne pour l’attribut. | 16 | ||
nom | Y | Le nom de l’attribut, tel qu’il apparaît sur les rapports et les feuilles. | Actifs à court terme | ||
code
Disponible dans l’API v39+. | Y | Le code de l'attribut. | Actifs à court terme | ||
shortName | Le nom abrégé de l'attribut. Le nombre maximum de caractères est 2 048. | Actifs | |||
displayNameType
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage. | N | Contrôle l'affichage des valeurs d'attributs. 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 | ||
importAutoCreateValues | N | "1" signifie que les valeurs d’attribut pour cet attribut peuvent être créées via l’importation, "0" (ou non indiqué) signifie qu’elles ne peuvent pas. | 1 | ||
type | Y | Le type de l'attribut. Ce sera 'account' si l'attribut est pour un compte, 'level' si l'attribut est pour un niveau, ou 'dimension' si l'attribut est pour une dimension. | compte | ||
listDimensionName | N | Le nom de la dimension de liste si l'attribut est de type 'dimension'. | Education | ||
description | N | Description textuelle de l’attribut, le cas échéant, telle qu’elle est entrée dans l’administration des attributs | Total des actifs courants | ||
keepSorted | Y | "1" indique que les valeurs de cet attribut sont toujours triées par ordre alphabétique. « 0 » (ou non précisé) signifie que les valeurs d’attribut sont triées en fonction de leur position dans la charge utile de la demande. Si le XML contient à la fois le parent et au moins un apparenté d’une valeur d’attribut hiérarchique non répertoriée, la valeur non répertoriée est déplacée à la fin des semblables répertoriés pendant la mise à jour (en réorganisant les enfants du parent, tous les enfants de mêmes parents inscrits sur la liste viennent en premier, dans l’ordre dans lequel ils sont précisés dans le XML. Tous les congés non répertoriés viennent en dernier, dans l’ordre qu’ils ont déjà dans le système). garderSorted s’applique aux enfants de chaque valeur d’attribut parent. | 1 | ||
statut | Y | Le statut de la valeur d’attribut suivant. 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.
| Mis à jour | ||
message | N | Le message d'erreur pour l'entrée de l'attribut. | L’attribut Secteur d’activité est soit en double dans les données utiles, soit déjà dans le système avec l’identifiant 8 | ||
Contenu de l'élément
| |||||
Zéro 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 une valeur de 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
|
identifiant | Y | Le numéro d'identifiant de système interne pour cette valeur de membre de l'attribut. | 34 |
code
Disponible uniquement dans l’API v30+ pour les instances qui activent le nom d’affichage. | N | Le code unique de la valeur de l'attribut. | Disponible |
nom | Y | Étiquette de la valeur membre de l'attribut telle qu'elle est affichée sur la page d'administration de l'attribut. | Disponible |
shortName | N | Nom abrégé de la valeur de l'attribut. | Moyenne |
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 changements se répercutent dans les enfants de ce niveau. 0 pour non, 1 pour oui. | 0 |
statut | Y | Le statut de l’attribut suivant est mis à 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.
| mis à jour |
message | N | Le message d'erreur pour une entrée attributeValue non valide. | |
Contenu de l'élément
| |||
Zéro 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 sont implicitement regroupés dans cette valeur. | |||