importConfigurableModelData
Mis à jour dans API v40 (21 septembre 2024).
Catégorie
| Soumission de données |
Description
| Insère, remplace ou met à jour les données dans une feuille modèle. |
Autorisations requises pour appeler
| Importer |
Paramètres obligatoires à la demande
| Identifiants, ImportDataOptions, Version, Feuille, RowData |
La demande de cette méthode contient les paramètres qui seront utilisés pour déterminer quelle feuille et quelle version vont recevoir les lignes de données fournies.
Ce mode peut :
- Ajoutez de nouvelles lignes à la feuille.
- Remplacez toutes les lignes figurant actuellement sur la feuille modèle par l'import.
- Remplacer toutes les données de la feuille, mais uniquement pour les périmètres importés
- Mettez à jour les lignes existantes en faisant correspondre les lignes de l'import avec une clé d'import.
- Mettez à jour les lignes existantes en faisant correspondre les lignes de l'import avec une clé d'import, puis ajoutez de nouvelles lignes.
Chaque invocation de cet appel d'API doit contenir exactement un élément de chacun des types répertoriés :
- identifiants
- importDataOptions
- version
- feuille
- rowData
Une incohérence entre le nombre de caractères du trait vertical (|) dans l'en-tête et les données va entraîner une erreur pour l'API v30 ou supérieure.
À partir de API v37, nous limitons le nombre maximum de nouvelles lignes que vous pouvez importer dans les feuilles modèles. Contactez le support si vous rencontrez cette limite.
Format de demande
<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" useMappings="false" replaceExisting="2"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Level|Region|Title|JobCode|Benefits|per|Last Name|First Name|ID|Start|End|Hr/Week|Pay Rate|Pay Rate Display Column</header> <rows> <row>Corporate Plan|Any|CEO|E1|Yes|Yr|Topdog|Andy|1000|12/20/2013|12/30/2014|80|500,000.12|888,888</row> </rows> </rowData> </call>
Format de la demande de mise à jour des lignes existantes avec import Key
<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" replaceExisting="3" importKey="Region" allowParallel="false" moveBPtr="false" useMappings="false"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Plan|Region|Benefits|per</header> <rows> <row>Europe Sales|W-US|Yes|Hr</row> </rows> </rowData> </call>
élément identifiants
Nom du marqueur
| identifiants | ||
Description
| Tous les appels d'API doivent contenir un seull'é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 période 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 importDataOptions
| |||
Nom du marqueur
| importDataOptions | ||
Description
| Indique les options à utiliser lors de l'import. | ||
Attributs de l'élément
| |||
Nom de l'attribut
| Obligatoire ?
| Valeur
| Exemple
|
planOrActuals | O | Définir sur l'un desPlan ouMontants réels pour indiquer le type de données importées. Si ce paramètre est en conflit avec la version indiquée dans le marqueur de version, la valeur du marqueur de version prévaut et ce paramètre est ignoré. | Le plan |
moveBPtr | N | Utilisé uniquement lorsque les données importées comportent un ensemble de nombres d'intervalles de temps pour chaque ligne. SimoveBPtr est défini surtrue, l'import déplacera le pointeur de disponibilité des montants réels dans la version des montants réels pour qu'il corresponde à la dernière période trouvée dans les données importées. En cas defalse (faux), l'import n'affectera pas les périodes qui affichent des montants réels dans aucune version. Cet attribut doit être défini sur false (faux) si planOrActuals est défini sur Plan. | false |
AllowParallel | O | En cas detrue (vrai), l'import se poursuivra même s'il existe déjà un autre import de montants réels ou de transactions en cours pour cette instance. En cas defalse (faux), la tentative d'import échouera si un import de montants réels ou de transactions est déjà en cours pour cette instance. | false |
useMappings | N | Indique s'il faut utiliser des mappages d'import pour les comptes, les plans et les valeurs de dimension à l'intérieur des éléments de ligne. EnvisagéVrai par défaut. Sifalse (faux), alors les identifiants internes doivent être utilisés : les comptes sont identifiés par leur code, les périmètres et les valeurs de dimension par leur nom. | false |
remplacerExistant | N | Définir sur '1' ou 'vrai' pour remplacer toutes les lignes existantes dans tous les périmètres par les nouvelles lignes en cours d'import (c.-à-d. effacer toutes les lignes précédemment existantes dans tous les périmètres). Seuls les utilisateurs disposant de l'autorisation d'importer dans tous les emplacements peuvent utiliser cette option.Indiquez "0" ou "faux" pour ajouter les lignes importées aux lignes existantes, même si les nouvelles lignes sont des doublons. Affectez la valeur "2" pour remplacer les lignes existantes dans la feuille modèle par les nouvelles lignes en cours d'import, mais uniquement pour les lignes avec des dimensions sécurisées et de périmètre correspondantes. Les lignes existantes combinées à un périmètre et à des dimensions sécurisées ne figurant pas dans la feuille de calcul téléchargée ne verront pas leurs lignes existantes, sauf si la ligne était une subdivision d'une ligne que le téléchargement est en cours de remplacement. RemplacerExistant examine les dimensions utilisées et si des données existent dans le même périmètre, le même compte, la même période et la même version. S'il existe une clé de ligne, nous établirons aussi une correspondance avec la ou les colonne(s) de clés de ligne. S'il existe des données au même endroit dans le système, l'import les remplacera. Ce remplacement s'effectue ligne par ligne. L'import ne remplace pas tout simultanément. Les lignes d'import sans correspondance sont ajoutées à la feuille. Par exemple, vous effectuez deux imports. Votre premier fichier d'import charge les données que votre deuxième fichier d'import ne contient pas. Les données existantes resteront après le deuxième import. Si vous souhaitez supprimer toutes les données d'une colonne spécifique, incluez-la, mais laissez ses valeurs vides. Les valeurs des colonnes non mentionnées restent inchangées. Définissez sur "3" pour mettre à jour les lignes existantes dans la feuille modèle afin de refléter les nouvelles lignes en cours d'importation. Un avertissement sera renvoyé si une ligne ne correspond pas à une ligne existante. Ce mode nécessite une import Key. Les feuilles dont l'option Autoriser les subdivisions
Définissez sur "4" pour mettre à jour les lignes existantes dans la feuille modèle afin de refléter les nouvelles lignes en cours d'import, et insérer de nouvelles lignes pour celles qui ne correspondent à aucune ligne existante. Ce mode nécessite une import Key. Les seules colonnes obligatoires sont Clé d'import, Périmètre et n'importe quel sélecteur de texte, même lorsque vous n'ajoutez pas de nouvelles lignes. Les feuilles dont l'option Autoriser les subdivisions
Définissez sur 5 pour remplacer les lignes existantes en fonction du périmètre qui prend actuellement uniquement en charge les périmètres de saisie pour la fonctionnalité Remplacer par périmètre uniquement. Le champ d'application est fourni à l'aide d'un nouvel élément de champ d'application. Seules les lignes correspondant au périmètre donné seront remplacées par les données utiles de l'import. Les lignes qui ne correspondent pas au périmètre ne seront pas affectées. La valeur par défaut est Vrai. | vrai |
importkey | N | Le nom de la colonne de feuille modèle à utiliser comme clé d'import lors de la mise à jour des lignes de feuille modèle. Adaptive Planning utilise la colonne Clé d'import pour faire correspondre chaque ligne de l'import aux lignes de la feuille modèle. La valeur de clé d'import de chaque ligne doit être unique.Cet attribut ne peut être utilisé que lorsque remplacerExisting a pour valeur "3" ou "4". Les colonnes clés d'import peuvent être l'une des suivantes :
| Périmètre |
includeContext | N | Indique si les messages peuvent inclure le bloc de contexte. Les valeurs sontfalse (ne jamais afficher le contexte) ouvrai (afficher le contexte le cas échéant). Si aucune valeur n'est indiquée :true (vrai) est supposée. | false |
displayNameEnabled
Uniquement disponible dans API v31 et supérieure pour les instances qui activent le nom d'affichage. | N | displayNameEnabled=true indique que l'API doit rechercher les colonnes Code du compte, Code du périmètre, Code de la dimension et Nom de la dimension dans les données utiles lorsque le paramètre Activer le nom d'affichage est activé pour l'instance. displayNameEnabled=false indique que l'API doit continuer après le contrat API pré-v30, même lorsque le paramètre Activer le nom d'affichage est activé pour l'instance. La valeur par défaut pour displayNameEnabled est "faux". | false |
applyValidationRules
Disponible uniquement dans API v38 et supérieure. | N | applyValidationRules=true indique que l'API effectuera des validations de règles de feuille modèle pour toutes les données importées lorsque la version de l'API sera supérieure à v38.
applyValidationRules=false indique que l'API va ignorer les validations de règles de feuille modèle pour toutes les données importées. La valeur par défaut d'appliValidationRules est "true". | false |
Contenu de l'élément
| |||
(aucun) | |||
élément de version
| |||
Nom du marqueur
| version | ||
Description
| Indique quelle version doit être utilisée pour recevoir les données demandées. Une version doit être indiquée pour chaque appel. | ||
Attributs de l'élément
| |||
Nom de l'attribut
| Obligatoire ?
| Valeur
| Exemple
|
nom | N | Nom de la version à utiliser pour recevoir les données. Une seule version peut être accessible dans un même appel d'API. Si aucun nom n'est indiqué, leL'indicateur isDefault doit être défini survrai sur cet élément. | Budget 2014 |
isDefault | N | Si l'appelant souhaite accéder à la version par défaut actuelle de l'instance, quel que soit son nom, cet attribut peut être défini sur true (vrai), auquel cas l'attribut de nom du marqueur (s'il est présent) est ignoré. Sinon, si cette valeur est "faux" ou si cet attribut n'est pas présent, une version avec le nom fourni doit exister et être accessible à l'utilisateur pour que cet appel fonctionne. | false |
Contenu de l'élément
| |||
(aucun) | |||
élément de feuille
| |||
Nom du marqueur
| feuille | ||
Description
| Indique quelle feuille doit recevoir les données importées. Chaque appel d'API ne peut cibler que les données d'une seule feuille. | ||
Attributs de l'élément
| |||
Nom de l'attribut
| Obligatoire ?
| Valeur
| Exemple
|
nom | O | Le nom de la feuille vers laquelle les données seront importées. | Personnel |
isUserAssigned | N | Indique qu'il s'agit d'une feuille affectée à un utilisateur. Si aucune valeur n'est indiquée, la valeur par défaut est false (faux), ce qui indique qu'il s'agit d'une feuille affectée à un périmètre. | false |
Contenu de l'élément
| |||
(aucun) | |||
Élément du champ d'application
| |||
Nom du marqueur
| Champ d'application (disponible avec API v40) | ||
Description
| Indique le périmètre de cet import. Exemple :
Autorisé uniquement lorsque l'attribut remplaceExisting de l'élément importDataOptions est 5. | ||
Élément rowData
| |||
Nom du marqueur
| rowData | ||
Description
| Conteneur pour les lignes de données en cours d'import. | ||
Attributs de l'élément
| |||
(aucun) | |||
Contenu de l'élément
| |||
Totalement unélément d'en-tête et exactement unélément rows. | |||
élément d'en-tête
| |||
Nom du marqueur
| en-tête | ||
Description
| Indique les noms et l'ordre des colonnes de données dans les colonnes correspondantes.élément rows. | ||
Attributs de l'élément
| |||
(aucun) | |||
Contenu de l'élément
| |||
Une ligne de texte avec des noms de colonne séparés par des barres verticales. Ces noms de colonne doivent correspondre aux noms des dimensions ou des champs de la feuille ou aux codes des périodes qui peuvent contenir des données. Ils sont identiques aux noms de colonne qui se trouvent dans le modèle d'import de la feuille vers laquelle les données sont importées. Chaque en-tête de colonne est quant à lui séparée du suivant par un symbole de barre verticale ou de trait vertical | .
Pour les instances qui activent le Nom d'affichage, l'en-tête ne prend pas en charge "<dimension>" en combinaison avec "<dimension> Name" ou "<dimension> Code" dans API v30 ou supérieure pour les paramètres régionaux pris en charge par Adaptive Planning. | |||
élément de lignes
| |||
Nom du marqueur
| lignes | ||
Description
| Conteneur pour un ou plusieursdes éléments de ligne. | ||
Attributs de l'élément
| |||
(aucun) | |||
Contenu de l'élément
| |||
Un ou plusieursdes éléments de ligne. | |||
élément de ligne
| |||
Nom du marqueur
| ligne | ||
Description
| Données d'une ligne unique en cours d'import. | ||
Attributs de l'élément
| |||
(aucun) | |||
Contenu de l'élément
| |||
Les données des champs d'une seule ligne en cours d'importation, valeur de chaque champ séparée par un symbole de barre verticale ou de trait vertical. Les champs de données doivent être dans le même ordre que la ligne dans l'élément d'en-tête. Si les chiffres dans les valeurs utilisent des séparateurs de milliers, ils sont supposés être les séparateurs de virgules utilisés dans les paramètres régionaux indiqués dans les identifiants de la demande. | |||
Format de la réponse
Voici des exemples de réponses pour une importation de données réussie ou non.
Exemple de réussite
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <messages> <message key="modeled-import-success">Personnel import successful. Rows imported: 1</message> <message key="modeled-import-replace">All existing rows were replaced.</message> </messages> </response>
Échec (avec contexte)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate"> <context> <col header="Plan" value="Development1" /> <col header="Region" value="C-US" /> <col header="Title" value="CEO" /> <col header="JobCode" value="E1" /> <col header="Benefits" value="Yes" /> <col header="per" value="Yr" /> <col header="Last Name" value="Topdog" /> <col header="First Name" value="Andy" /> <col header="ID" value="1000" /> <col header="Start" value="12/20/2013" /> <col header="End" value="12/30/2014" /> <col header="Hr/Week" value="80.0" /> <col header="Pay Rate" value="500000.12" /> <col header="Pay Rate Display Column" value="888,888" /> </context> Invalid Level Choice: Development1 on row 1 column A </message> </messages> </response>
Échec (sans contexte)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate">Invalid Level Choice: Development1 on row 1 column A</message> </messages> </response>
élément de réponse
| |||
Nom du marqueur
| réponse | ||
Attributs de l'élément
| |||
Nom de l'attribut
| Obligatoire ?
| Valeur
| Exemple
|
réussite | O | Matriciel ou subordonnévrai oufalse (faux), indiquant si l'appel d'API a réussi ou non. Même les appels traités avec succès peuvent contenir des messages d'avertissement dans leur réponse. | vrai |
Contenu de l'élément
| |||
Un seul facultatifL'élément Messages. | |||
élément de message
| |||
Nom du marqueur
| messages | ||
Description
| Conteneur pour un ou plusieursÉléments de message. | ||
Attributs de l'élément
| |||
(aucun) | |||
Contenu de l'élément
| |||
Un ou plusieursÉléments de message. | |||
élément de message
| |||
Nom du marqueur
| message | ||
Description
| Représente un message que le système renvoie à l'appelant. Les messages sont utilisés pour les messages d'erreur lorsque les demandes n'ont pas abouti, pour les messages d'avertissement lorsque les demandes ont abouti et pour les messages de confirmation lorsque les demandes ont abouti. | ||
Attributs de l'élément
| |||
Nom de l'attribut
| Obligatoire ?
| Valeur
| Exemple
|
clé | N | Lorsqu'elle est fournie, une clé permet d'identifier un message ou un type de message particulier, utile pour l'enregistrement et la récupération automatisés des erreurs dans les programmes clients. Les clés ne changent pas selon les paramètres régionaux des demandes, même lorsque la langue du message change. Il est également peu probable que les clés changent à l'avenir en raison d'ajustements du libellé ou de la terminologie. | invalid-attributvalueid |
Contenu de l'élément
| |||
| |||
élément de contexte
| |||
Nom du marqueur
| context | ||
Description
| Conteneur pour un ou plusieurs éléments de col. | ||
Attributs de l'élément
| |||
Nom de l'attribut
| Obligatoire ?
| Valeur
| Exemple
|
aucun(e) | |||
Contenu de l'élément
| |||
Un ou plusieurs éléments de col. | |||
élément col
| |||
Nom du marqueur
| col | ||
Description
| Représente le contexte du message. Fournit une paire en-tête/valeur afin que la ligne générant le message puisse être identifiée. | ||
Attributs de l'élément
| |||
Nom de l'attribut
| Obligatoire ?
| Valeur
| Exemple
|
en-tête | O | L'en-tête de la colonne. | "Account" |
valeur | O | Valeur de la colonne. | "GL-29482-38233" |
Contenu de l'élément
| |||
(aucun) | |||