importConfigurableModelData
Mis à jour dans l’API v40 (21 septembre 2024).
Catégorie | Soumission de données |
Description | Insère, remplace ou met à jour des données dans une feuille modélisée. |
Autorisations obligatoires pour pouvoir être appelées | Importer |
Paramètres requis sur demande | Données d’identification, 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 recevront les rangées de données fournies.
Cette méthode peut :
- Ajoutez de nouvelles rangées à la feuille.
- Remplacer toutes les rangées actuellement dans la feuille modélisée par l’importation.
- Remplacer toutes les données de la feuille, mais uniquement pour les niveaux importés
- Mettez à jour les rangées existantes en faisant correspondre les rangées de l’importation avec une clé d’importation.
- Mettez à jour les rangées existantes en faisant correspondre les rangées de l’importation avec une clé d’importation, puis ajoutez de nouvelles rangées.
Chaque invocation de cet appel d’API doit contenir exactement un élément de chacun des types répertoriés :
- données d'identification
- importDataOptions
- version
- feuille
- rowData
Une non-correspondance entre le nombre de caractères de canal (|) dans l’en-tête et les données générera une erreur pour l’API v30 ou une version plus récente.
À compter de la version 37 de l’API, nous limitons le nombre maximum de nouvelles rangées que vous pouvez importer dans les feuilles modélisées. Contactez le service de soutien 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 demande pour la mise à jour des rangées existantes avec l'option 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 de données d'identification
Nom du marqueur | données d'identification | ||
Description | Tous les appels d'API doivent contenir un seulun élément d’identification pour désigner 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 période 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 ImportDataOptions | |||
Nom du marqueur | importDataOptions | ||
Description | Indique les options à utiliser lors de l'importation. | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire? | Valeur | Exemple |
planOrActuals | Y | Défini à l'une des valeurs suivantesRégime ouChiffres réels pour préciser le type de données importées. Si ce paramètre est en conflit avec la version indiquée dans le marqueur Version, la valeur du marqueur Version a priorité et ce paramètre est ignoré. | Plan |
moveBPtr | N | Utilisé uniquement lorsque les données importées comportent un ensemble de numéros d’intervalle de temps pour chaque rangée. SimoveBPtr est défini àvrai, l’importation déplacera le pointeur de disponibilité des chiffres réels dans la version des chiffres réels pour qu’il corresponde à la dernière période trouvée dans les données importées. Si la valeur estfaux, l’importation n’aura aucune incidence sur les périodes qui affichent les chiffres réels dans les versions. Cet attribut doit être défini à Faux si planOrActuals est défini à Plan. | false |
AllowParallel | Y | Si la valeur estVrai, alors l’importation se poursuivra même s’il existe déjà une autre importation de chiffres réels ou de transactions en cours pour cette instance. Si la valeur estfaux, alors une tentative d’importation échouera si une importation de chiffres réels ou de transactions est déjà traitée pour cette instance. | false |
useMappings | N | Indique si vous souhaitez utiliser des mappages d’importation pour les comptes, les plans et les valeurs de dimension dans les éléments de rangée. ÉtudiéVrai par défaut. Sifaux, alors les identifiants internes doivent être utilisés : les comptes sont repérés par un code, les niveaux et les valeurs de dimension par nom. | false |
Remplacerexistant | N | Définissez la valeur à « 1 » ou à « Vrai » pour remplacer toutes les rangées existantes de tous les niveaux par les nouvelles rangées en cours d’importation (c’est-à-dire effacer toutes les rangées existantes précédemment dans tous les niveaux). Seuls les utilisateurs disposant de l’autorisation Importer tous les emplacements peuvent utiliser cette option.Réglez à « 0 » ou « faux » pour ajouter les rangées importées aux rangées existantes, même si les nouvelles rangées sont des doublons. Réglez à « 2 » pour remplacer les rangées existantes dans la feuille modélisée par les nouvelles rangées en cours d’importation, mais uniquement pour les rangées avec des dimensions de niveau et des dimensions sécurisées correspondantes. Les combinaisons de rangées de niveau et de dimensions sécurisées qui n’ont pas de rangées non fractionnées dans la feuille de calcul téléversée ne verront pas leurs rangées existantes retirées, sauf si la rangée était une subdivision d’une rangée remplacée par le téléversement. RemplacerExistant examine les dimensions utilisées et si les données existent dans le même niveau, le même compte, la même période et la même version. S’il existe une clé de rangée, nous établissons également la correspondance avec la ou les colonnes clés de rangée. Si des données existent dans le système au même emplacement, l’importation les remplace. Ce remplacement s’effectue rangée par rangée. L'importation ne remplace pas tout en même temps. Les lignes d'importation sans correspondance s'ajoutent à la feuille. Par exemple, vous effectuez deux importations. Votre premier fichier d’importation charge des données que votre deuxième fichier d’importation ne contient pas. Les données existantes seront conservées après la deuxième importation. Si vous souhaitez supprimer toutes les données d’une colonne particulière, incluez la colonne, mais laissez ses valeurs de colonne vides. Les valeurs de colonne pour les colonnes non mentionnées restent inchangées. Réglez à "3" pour mettre à jour les rangées existantes dans la feuille modélisée afin de refléter les nouvelles rangées en cours d'importation. Un avertissement sera renvoyé si une ligne ne correspond pas à une rangée existante. Ce mode nécessite une Import Key. Les feuilles pour lesquelles l'option Autoriser les subdivisions Réglez à « 4 » pour mettre à jour les rangées existantes dans la feuille modélisée afin de refléter les nouvelles rangées importées, et insérer de nouvelles rangées pour celles qui ne correspondent pas à une rangée existante. Ce mode nécessite une Import Key. Les seules colonnes obligatoires sont Clé d’importation, Niveau et n’importe quel sélecteur de texte, même lorsque vous n’ajoutez pas de nouvelles lignes. Les feuilles pour lesquelles l'option Autoriser les subdivisions Définissez la valeur 5 pour remplacer les rangées existantes en fonction du champ d’application qui prend actuellement uniquement en charge les niveaux d’entrée pour la fonctionnalité Remplacer par niveau uniquement. Le champ d'application est fourni à l'aide d'un nouvel élément de champ d'application. Seules les rangées qui correspondent au champ d'application donné seront remplacées par les données utiles dans l'importation. Les lignes qui ne correspondent pas au champ d'application ne seront pas affectées. La valeur par défaut est vraie. | true |
importKey | N | Le nom de la colonne de la feuille modélisée à utiliser comme clé d’importation lors de la mise à jour des rangées de la feuille modélisée. Adaptive Planning utilise la colonne de clé d’importation pour faire correspondre chaque rangée de l’importation aux rangées de la feuille modélisée. La valeur de la clé d'importation de chaque ligne doit être unique.Cet attribut peut uniquement être utilisé lorsque RemplaceExisting est à "3" ou à "4". Les colonnes clés de l’importation peuvent être l’une des suivantes :
| Niveau |
includeContext | N | Indique si les messages peuvent inclure le bloc de contexte. Les valeurs sontfaux (ne jamais afficher le contexte) ouvrai (afficher le contexte, le cas échéant). Si non précisé,Vrai est postulé. | false |
displayNameEnabled
Disponible uniquement dans l’API v31+ pour les instances qui activent le nom d’affichage. | N | displayNameEnabled=true indique que l’API doit attendre les colonnes Code de compte, Code de niveau, Code de 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. afficherNameEnabled=false indique que l’API doit continuer à suivre le contrat d’API avant la version 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 « false ». | false |
applyValidationRules
Disponible uniquement dans l’API v38 +. | N | applyValidationRules=true indique que l’API effectuera des validations de règles de feuille modélisée pour toutes les données importées lorsque la version de l’API est supérieure à v38.
applyValidationRules=false indique que l'API ignore les validations de règles propres aux feuilles modélisées pour toutes les données importées. La valeur par défaut pour applyValidationRules est "true". | false |
Contenu de l'élément | |||
(aucun) | |||
élément de version | |||
Nom du marqueur | version | ||
Description | Indique la version à utiliser pour recevoir les données demandées. Une version doit être fournie pour chaque appel. | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire? | Valeur | Exemple |
nom | N | Le nom de la version à utiliser pour recevoir les données. Une seule version est accessible dans un seul appel d'API. Si aucun nom n’est fourni, leL’indicateur isDefault doit être défini àvrai 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 à Vrai; auquel cas l’attribut de nom du marqueur (s’il est présent) est ignoré. Sinon, si cette valeur est fausse 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 réussisse. | 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 | Y | Le nom de la feuille dans laquelle les données seront importées. | Personnel |
isUserAssigned | N | Indique qu’il s’agit d’une feuille affectée à un utilisateur. Si elle n’est pas précisée, la valeur par défaut est fausse, ce qui indique qu’il s’agit d’une feuille avec un niveau affecté. | false |
Contenu de l'élément | |||
(aucun) | |||
Élément de cadre | |||
Nom du marqueur | Étendue (disponible avec l’API v. 40) | ||
Description | Indique le champ d'application de cette importation. 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 rangées de données importées. | ||
Attributs de l'élément | |||
(aucun) | |||
Contenu de l'élément | |||
Un seulélément d'en-tête et une valeur exacteélément de rangées. | |||
élément d'en-tête | |||
Nom du marqueur | en-tête | ||
Description | Indique le nom et l'ordre des colonnes de données dans le rapport correspondant.élément de rangées. | ||
Attributs de l'élément | |||
(aucun) | |||
Contenu de l'élément | |||
Une ligne de texte avec des noms de colonnes séparés par des barres verticales. Ces noms de colonnes doivent correspondre aux noms des dimensions ou aux champs de la feuille, ou aux codes des périodes temporelles pouvant contenir des données. Ils sont identiques aux noms de colonnes qui se trouvent dans le modèle d’importation de la feuille vers laquelle les données sont importées, chaque en-tête de colonne étant séparé du suivant par une barre verticale ou une barre verticale. .
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 l'API v30 ou une version plus récente pour les paramètres régionaux pris en charge par Adaptive Planning. | |||
élément rows | |||
Nom du marqueur | lignes | ||
Description | Conteneur pour une ou plusieurs valeurséléments de rangée. | ||
Attributs de l'élément | |||
(aucun) | |||
Contenu de l'élément | |||
Une ou plusieurséléments de rangée. | |||
élément de rangée | |||
Nom du marqueur | rangée | ||
Description | Données pour une seule rangée en cours d'importation. | ||
Attributs de l'élément | |||
(aucun) | |||
Contenu de l'élément | |||
Les données pour les champs d’une seule rangée en cours d’importation, les valeurs de chaque champ étant séparées par une barre verticale ou une barre verticale. 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 nombres dans les valeurs utilisent des séparateurs de milliers, ils sont considérés comme des séparateurs de virgules utilisés dans les paramètres régionaux indiqués dans les données d’identification de la demande. | |||
Format de réponse
Voici des exemples de réponses pour une importation de données réussie et non réussie.
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 | Y | L'un ou l'autrevrai oufaux, indiquant si l’appel d’API a réussi ou non. Même les appels réussis peuvent contenir des messages d’avertissement dans leur réponse. | vrai |
Contenu de l'élément | |||
Un seul facultatifélément de messages. | |||
élément de message | |||
Nom du marqueur | messages | ||
Description | Conteneur pour une ou plusieurs valeurséléments de message. | ||
Attributs de l'élément | |||
(aucun) | |||
Contenu de l'élément | |||
Une ou plusieurséléments de message. | |||
élément de message | |||
Nom du marqueur | message | ||
Description | Représente un message renvoyé par le système à l’appelant. Les messages sont utilisés pour envoyer des messages d’erreur lorsque les demandes échouent, pour envoyer des messages d’avertissement lorsque les demandes réussissent et pour les messages de confirmation lorsque les demandes réussissent. | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire? | Valeur | Exemple |
clé | N | Lorsqu’elle est fournie, une clé est un moyen de repérer un message ou un type de message particulier, ce qui est utile à des fins d’enregistrement automatique d’erreurs et de récupération 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 improbable que les clés changent à l’avenir en raison d’ajustements de formulation ou de changements de terminologie. | invalid-attributevalueid |
Contenu de l'élément | |||
| |||
élément de contexte | |||
Nom du marqueur | context | ||
Description | Conteneur pour un ou plusieurs éléments col. | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire? | Valeur | Exemple |
aucun | |||
Contenu de l'élément | |||
Un ou plusieurs éléments col. | |||
élément de col | |||
Nom du marqueur | col | ||
Description | Représente le contexte du message. Donne une paire en-tête/valeur afin de pouvoir repérer la rangée générant le message. | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire? | Valeur | Exemple |
en-tête | Y | L’en-tête de la colonne. | "Account" |
valeur | Y | La valeur dans la colonne. | « GL-29482-38233 » |
Contenu de l'élément | |||
(aucun) | |||