importStandardData
Mis à jour dans l’API v40 (13 septembre 2024)
Catégorie
| Soumission de données |
Description
| Insère ou remplace des données dans les comptes standard. |
Autorisations obligatoires pour pouvoir être appelées
| Importer tous les emplacements
Effacer les données (API v36+ pour prendre en charge le mode REMPLACER) |
Paramètres requis sur demande
| Données d’identification, ImportDataOptions, Version, RowData |
includeDescendants
La demande de cette méthode contient les paramètres qui seront utilisés pour déterminer la version qui recevra les rangées de données fournies. Les données peuvent être importées dans n’importe quel compte standard (compte GL, compte personnalisé, hypothèse ou taux de change), que le compte ait été placé ou non sur une feuille.
ImportStandardData ne peut pas effectuer d'importation dans des comptes qui utilisent
Saisie de données
pour le paramètre de formule de remplacement
.Format de demande
<?xml version='1.0' encoding='UTF-8'?> <call method="importStandardData" 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" /> <version name="Budget 2004" isDefault="false" /> <rowData> <header>Account|Level|Split Label|Product|Region|11/2005|01/2006</header> <rows> <row>70110|Corporate Plan||Bunnyrabbit Toy|Western-US|2037|4032</row> </rows> </rowData> </call>
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
- rowData
- en-tête
- lignes
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.
Pour l’API v36+, si l’attribut de mode ImportDataOptions est REplace, un élément de champ d’application doit également être précisé :
Exemple : demande du mode Remplacer
|
Disponible uniquement dans l'API v36+
|
é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 nombres et les dates entrants, et pour mettre en forme les nombres et les dates sortants (à l’aide du séparateur de milliers approprié,les noms des périodes temporelles et le format de date). 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 suivantes :Plan" ou "Chiffres 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 leMarqueur de version, leLa valeur du marqueur de version a la priorité et ce paramètre est ignoré. | Plan | ||||
moveBPtr | N | Utilisé uniquement lorsquel'attribut planOrActuals est défini surChiffres réels. 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 siplanOrActuals est défini àPlan. | false | ||||
AllowParallel | Y | Utilisé uniquement lorsquel'attribut planOrActuals est défini surChiffres réels. 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 | ||||
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 v30+ pour les instances qui activent le nom d’affichage. | N | displayNameEnabled=true indique que l’importation de l’importation de Standard doit être attendue Account Code , Level Code , Dimension Code , et Dimension Name Column dans les données utiles lorsque l’option Activer le nom d’affichage est ACTIVÉE pour l’instance.displayNameEnabled=false indique que l’API ImportStandardData doit continuer à suivre le contrat de l’API antérieure à la version v30, même lorsque l’option Activer le nom d’affichage est ACTIVÉE pour l’instance. L'API ImportStandardData ignore les propriétés du nom d'affichage Account Code , Level Code , Dimension Code , et Dimension Name Column .La valeur par défaut pour displayNameEnabled est « false ». | false | ||||
splitsToUnsplit
Disponible uniquement dans l'API v40+ | N | splitsToUnsplit=true autorisent l’importation de subdivisions dans un emplacement non fractionné avec des données existantes. La valeur par défaut de cet attribut est Faux. | false | ||||
mode
Disponible uniquement dans l'API v36+ | N | Indique le mode d’importation, qui est APPEND ou REMPLACER.
Cet attribut de mode est pris en charge à partir de l'API v36 et des versions ultérieures. L'appel d'une version antérieure de l'API avec mode="REplace" est une erreur. La valeur par défaut pour le mode lorsqu’elle n’est pas précisée est APPEND. | APPROUVER | ||||
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 pour cet élément.
Pour obtenir une liste des versions de devises converties ainsi que leurs noms, faites une demandeexportVersions avec currencyVersions=true dans l’élément d’inclusion. | 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 champ d'application
| |||
Nom du marqueur
| champ d'application
Uniquement disponible dans la version 36 de l'API | ||
Description
| Indique le champ d'application de cette importation.
Autorisé uniquement lorsque l'attribut de mode de l'élément ImportDataOptions est REMPLACER. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
eraseCellNotes | N | Indique s’il faut effacer ou non les notes de cellule dans le champ d’application. Doit être l’une des trois valeurs énumérées :
AUCUNE - Ne pas effacer les notes de cellule.TOUT - Effacer toutes les notes de cellule du champ d’application.MODIFIED_Only - efface les notes de cellule pour les cellules du champ d’application qui sont modifiées par l’importation. Cela inclut les cellules précédemment vides dans lesquelles des faits sont importés et les cellules dont les faits sont effacés.Si précisé, la valeur par défaut est NEE. | AUCUNE |
Contenu de l'élément
| |||
Un élément de temps , un élément de compte et un élément de niveau , tous obligatoires. | |||
élément des comptes
| |||
Nom du marqueur
| comptes
Uniquement disponible dans la version 36 de l'API | ||
Description
| Indique les comptes pour le champ d'application de l'importation. Si un compte précisé existe, mais qu’il n’y a aucune donnée pour ce compte dans les données d’importation, les données de ce compte seront supprimées pour l’intervalle de temps et le reste des coordonnées du champ d’application.
Autorisé uniquement lorsque l'attribut de mode de l'élément ImportDataOptions est REMPLACER. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
mode | Y | Indique le mode du champ d'application du compte. Doit être l'une des trois options suivantes.
Explicit - Si ce mode est précisé, nous nous attendons à voir un ou plusieurs sous-éléments de compte qui détermineraient le champ d'application des comptes pour l'importation.INPUT - Lorsque ce mode est précisé, le champ d’application du compte sera déterminé par l’ensemble unique de comptes présents dans les données d’importation.Note : les comptes mode="TOUT" n'est pas autorisé pour le champ d'application d'importation standard. | EXPLICITE |
Contenu de l'élément
| |||
Si le mode est INPUT , il ne doit pas y avoir de sous-éléments <account>.Si le mode est explicite , il doit y avoir un ou plusieurs sous-éléments <account>.Si le mode est Explicit et si un code de compte dans un sous-élément <account> n’est pas valide, l’ensemble de l’élément <accounts> et, par extension, le champ <Scope>, sera considéré comme non valide. Un message d'erreur sera inclus dans la réponse pour chaque code non valide. | |||
élément de compte
| |||
Nom du marqueur
| compte
Uniquement disponible dans la version 36 de l'API | ||
Description
| Indique le code de compte à inclure dans le champ d'application de l'importation.
Autorisé uniquement lorsque l'attribut de mode de l'élément ImportDataOptions est REMPLACER. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
includeDescendants | N | Si le compte est un compte feuille, IncludeDescendants n’a aucun effet.
Si le compte est un compte parent, le fait d’indiquer à cet attribut la valeur Vrai inclura tous les descendants feuilles de ce compte dans le champ d’application. Il s'agit d'une erreur si le compte est un compte parent et que la valeur de IncludeDescendants est fausse. Nous ne pouvons effectuer d'importation que vers les comptes de feuille. Cet attribut est facultatif et la valeur par défaut sera considérée comme fausse. | vrai |
sélecteur | N | Indique le type de contenu d'élément de compte :
La valeur par défaut du sélecteur est un code. | |
Contenu de l'élément
| |||
Le code de compte sensible à la casse du compte utilisé dans le cadre du champ d’application de l’importation. Par exemple, Comptes fournisseurs. Le code ne doit pas être vide et le compte correspondant au code doit exister. Le compte ne peut pas être un compte système ou un compte lié. Si le compte est un compte calculé, il doit exister un remplacement de saisie de données pour ce compte; sinon, il est considéré comme non valide.
Si un code de compte n’est pas valide, l’ensemble de l’élément <accounts> et, par extension, le champ <Scope> est considéré comme non valide. | |||
élément niveaux
| |||
Nom du marqueur
| niveaux
Uniquement disponible dans la version 36 de l'API | ||
Description
| Indique les codes de niveau pour le champ d'application de l'importation. Si un code de niveau est indiqué ici, mais qu'il n'y a aucune donnée pour ce niveau dans les données d'importation, les données de ce niveau seront supprimées pour l'intervalle de temps et le reste des coordonnées du champ d'application.
Autorisé uniquement lorsque l'attribut de mode de l'élément ImportDataOptions est REMPLACER. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
mode | Y | Indique le mode pour le champ d'application du niveau. Doit être l'une des trois options suivantes.
Explicit - Si ce mode est précisé, nous nous attendons à voir un ou plusieurs sous-éléments <niveau> qui détermineraient le niveau d’application pour l’importation.INPUT - Lorsque ce mode est spécifié, le champ d’application du niveau sera déterminé par l’ensemble unique de niveaux présents dans les données d’importation.TOUT - Quand ce mode est précisé, le champ d’application du niveau correspond à tous les niveaux pouvant être importés. | EXPLICITE |
Contenu de l'élément
| |||
Si le mode est INPUT ou TOUT, il ne doit pas y avoir de sous-éléments de niveau <niveau>.
Si le mode est Explicit, il doit y avoir un ou plusieurs sous-éléments <niveau>. Si le mode est Explicit et si un code de niveau d’un sous-élément <level> n’est pas valide, l’ensemble de l’élément <levels> et, par extension, l’élément <Scope>, sera considéré comme non valide. Un message d'erreur sera inclus dans la réponse pour chaque code non valide. | |||
élément de niveau
| |||
Nom du marqueur
| niveau
Uniquement disponible dans la version 36 de l'API | ||
Description
| Indique le code de niveau à inclure dans le champ d'application de l'importation.
Autorisé uniquement lorsque l'attribut de mode de l'élément ImportDataOptions est REMPLACER. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
includeDescendants | N | Si le niveau est un niveau parent, le fait de préciser cet attribut comme valeur vraie inclura tous les descendants feuilles de ce niveau, y compris lui-même (le nœud seulement) dans le champ d’application.
Il s'agit d'un attribut facultatif. Si l’attribut n’est pas fourni, la valeur par défaut sera fausse. Si l’attribut n’est pas fourni ou qu’il est fourni avec la valeur Faux et que le niveau précisé est un niveau parent, cela signifie que l’importation tient compte du nœud Seul (par exemple, Ingénierie seulement) pour ce niveau pour le champ d’application. Les enfants du niveau ne seront pas inclus dans le champ d'application sauf s'ils sont explicitement précisés par d'autres éléments de niveau. | vrai |
Contenu de l'élément
| |||
Indique le code sensible à la casse du niveau. Par exemple, <niveau>perfectionnement>. S’il y a un problème avec le code de niveau, par exemple un niveau où le code est introuvable, l’ensemble des <niveaux> et, par extension, la <étendue> est considéré comme non valide. Un message d'erreur sera inclus dans la réponse pour chaque code non valide. | |||
élément de temps
| |||
Nom du marqueur
| temps
Uniquement disponible dans la version 36 de l'API | ||
Description
| Indique un ou plusieurs intervalles de temps qui représentent le champ d'application pour le moment de l'importation.
Autorisé uniquement lorsque l'attribut de mode de l'élément ImportDataOptions est REMPLACER. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
mode | Y | Indique le mode pour le champ d'application des heures. Doit être l’une des trois options suivantes. INPUT - Lorsque ce mode est précisé, le champ d’application des heures sera déterminé par les codes d’entrée des heures dans le <header> élément. Si l’en-tête contient deux mois, le champ d’application de l’importation sera ces deux mois.Explicit - Si ce mode est précisé, nous nous attendons à voir un ou plusieurs sous-éléments timeRange qui détermineraient l’intervalle de temps pour l’importation.Version - Lorsque ce mode est spécifié, le champ d’application des heures correspond au début et à la fin de la version, y compris toute période de solde initiale.Si le mode est INPUT ou Version, aucun sous-élément timeRange n'est autorisé. Si des sous-éléments timeRange sont présents, cela sera traité comme une erreur. | DONNÉES ENTRANTES |
Contenu de l'élément
| |||
Un ou plusieurs éléments timeRange, sauf si le mode est INPUT ou Version. | |||
élément timeRange
| |||
Nom du marqueur
| timeRange
Uniquement disponible dans la version 36 de l'API | ||
Description
| Indique un intervalle de temps unique pour le champ d’application des heures.
Autorisé uniquement lorsque l'attribut de mode de l'élément ImportDataOptions est REMPLACER. | ||
Attributs de l'élément
| |||
Nom de l’attribut
| Obligatoire?
| Valeur
| Exemple
|
début | Y | La période de début de l’intervalle de temps d’importation. | 07/2021 |
fin | Y | Période de fin de l'intervalle de temps d'importation. | 08/2021 |
Contenu de l'élément
| |||
Un ou plusieurs éléments timeRange, sauf si le mode est INPUT ou Version. | |||
É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 à des codes de période temporelle 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és 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 l’importation réussie et non réussie de données de compte standard.
Exemple de réussite
<?xml version='1.0' encoding='UTF-8'?> <response success="true"></response>
Échec (avec contexte)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-empty-account"> <context> <col header="Account" value="" /> <col header="Level" value="Corporate Plan" /> <col header="Split Label" value="" /> <col header="Product" value="Bunnyrabbit Toy" /> <col header="Region" value="Western-US" /> <col header="11/2005" value="2037" /> <col header="01/2006" value="4032" /> </context> Account cannot be empty on row 1. </message> </messages> </response>
Échec (sans contexte)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-empty-account">Account cannot be empty on row 1.</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) | |||