importStandardData
Mise à jour dans API v40 (13 septembre 2024)
Catégorie | Soumission de données |
Description | Insère ou remplace les données dans les comptes standard. |
Autorisations requises pour appeler | Importer dans tous les emplacements
Effacer les données (API v36 et supérieure pour prendre en charge le mode Remplacer) |
Paramètres obligatoires à la demande | Identifiants, ImportDataOptions, Version, RowData |
includeDescendants
La demande de cette méthode contient les paramètres qui seront utilisés pour déterminer quelle version va recevoir les lignes 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'import dans des comptes qui utilisent
la 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 :
- identifiants
- importDataOptions
- version
- rowData
- en-tête
- lignes
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.
Pour API v36 et supérieure, si l'attribut de mode importDataOptions est REplace, un élément de champ d'application doit également être indiqué :
Exemple : demande du mode Remplacer |
Uniquement disponible dans API v36 et supérieure
|
é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 de milliers approprié),noms de période et format de date). 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 des "Plan" ou "Montants réels" pour indiquer le type de données importées. Si ce paramètre est en conflit avec la version indiquée dans lesMarqueur de version :La valeur du marqueur de version est prioritaire et ce paramètre est ignoré. | Le plan | ||||
moveBPtr | N | Utilisé uniquement lorsque :L'attribut planOrActuals est défini surMontants réels. 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) siplanOrActuals est défini surPlan. | false | ||||
AllowParallel | O | Utilisé uniquement lorsque :L'attribut planOrActuals est défini surMontants réels. 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 | ||||
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 v30 et supérieure pour les instances qui activent le nom d'affichage. | N | displayNameEnabled=true indique que importStandardData doit s'attendre 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 après le contrat API pré-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 "faux". | false | ||||
splitsToUnsplit
Uniquement disponible dans API v40 et supérieure | N | splitsToUnSplit=true permettent d'importer des subdivisions dans un emplacement non subdivisé avec des données existantes. La valeur par défaut de cet attribut est false (faux). | false | ||||
mode
Uniquement disponible dans API v36 et supérieure | N | Indique le mode d'import, qui est Ajouter ou Remplacer.
Cet attribut de mode est pris en charge par API v36 et les versions ultérieures. L'appel d'une version antérieure de l'API avec mode="replace" est une erreur. La valeur par défaut du mode lorsqu'elle n'est pas spécifiée est APPEND. | AJOUTER | ||||
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 sur true (vrai) sur cet élément.
Pour obtenir la liste des versions de devise converties et de leurs noms, faites une demandeexportVersions avec deviseVersions=true dans l'élément à inclure. | 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 du périmètre | |||
Nom du marqueur | périmètre
Uniquement disponible dans API version 36 et supérieure | ||
Description | Indique le périmètre de cet import.
Autorisé uniquement lorsque l'attribut 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 suivantes :
AUCUNE - Ne pas effacer les notes de cellule.TOUT : permet d'effacer toutes les notes de cellule du périmètre.MODIFICATION_UNIQUEMENT : effacez les notes de cellule pour les cellules du champ d'application qui sont modifiées par l'import. Cela concerne les cellules précédemment vides dans lesquelles des faits ont été importés, ainsi que les cellules dont les faits ont été effacés.Si la valeur eraseCellNotes n'est pas spécifiée, la valeur par défaut est NOne. | AUCUNE |
Contenu de l'élément | |||
Un élément temps , un élément comptes et un élément périmètres dont tous sont obligatoires. | |||
élément Comptes | |||
Nom du marqueur | comptes
Uniquement disponible dans API version 36 et supérieure | ||
Description | Indique les comptes du périmètre d'import. Si un compte spécifié existe mais qu'il n'existe aucune donnée pour ce compte dans les données d'import, les données de ce compte seront supprimées pour la plage de temps et le reste des coordonnées du périmètre.
Autorisé uniquement lorsque l'attribut mode de l'élément importDataOptions est Remplacer. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
mode | O | Indique le mode pour le périmètre du compte. Doit être l'une des trois options suivantes.
Expérience : si ce mode est spécifié, un ou plusieurs sous-éléments de compte détermineront le périmètre du compte pour l'import.Saisie d'élément de paie - lorsque ce mode est spécifié, le périmètre du compte sera déterminé par l'ensemble unique de comptes figurant dans les données d'import.Remarque : le mode comptes = ="TOUT" n'est pas autorisé pour le périmètre d'import standard. | EXPÉRIENCE |
Contenu de l'élément | |||
Si le mode est Saisie d'élément de paie , il ne doit y avoir aucun sous-élément <compte>.Si le mode est EXPLIQUE , il doit y avoir un ou plusieurs sous-éléments <compte>.Si le mode est EXPLIQUE et que l'un des codes d'un sous-élément <account> n'est pas valide, l'élément <accounts> (et par extension le périmètre <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 | account
Uniquement disponible dans API version 36 et supérieure | ||
Description | Indique le code du compte à inclure dans le périmètre de l'import.
Autorisé uniquement lorsque l'attribut 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, l'option Inclure les descendants n'a aucun effet.
Si le compte est un compte parent, le fait d'affecter cet attribut à true (vrai) va inclure tous les descendants feuilles de ce compte dans le périmètre. C'est une erreur si le compte est un compte parent et que includeDescendants a la valeur Faux. Nous pouvons uniquement effectuer des imports dans les comptes feuilles. Il s'agit d'un attribut facultatif dont 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 le code. | |
Contenu de l'élément | |||
Code du compte sensible à la casse utilisé dans le périmètre d'import. Par exemple, ComptesProcessus. Le code ne doit pas être vide et le compte correspondant doit exister. Le compte ne peut pas être un compte système ou un compte lié. Si le compte est un compte calculé, une saisie de données de remplacement doit avoir été effectuée pour ce compte, sinon il est considéré comme non valide.
Si le code d'un compte n'est pas valide, l'élément <accounts> (et par extension le périmètre <Scope>) est considéré comme non valide. | |||
élément périmètres | |||
Nom du marqueur | périmètre(s)
Uniquement disponible dans API version 36 et supérieure | ||
Description | Indique les codes de périmètre pour le périmètre d'import. Si un code de périmètre est indiqué ici mais qu'il n'existe aucune donnée pour ce périmètre dans les données d'import, les données de ce périmètre seront supprimées pour la plage de temps et le reste des coordonnées du périmètre.
Autorisé uniquement lorsque l'attribut mode de l'élément importDataOptions est Remplacer. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
mode | O | Indique le mode pour le périmètre. Doit être l'une des trois options suivantes.
Expérience : si ce mode est spécifié, nous nous attendons à voir un ou plusieurs sous-éléments <périmètre> qui détermineront l'étendue des périmètres pour l'import.Saisie d'élément de paie : lorsque ce mode est spécifié, la charge du périmètre sera déterminée par l'ensemble unique de périmètres figurant dans les données d'import.TOUS : lorsque ce mode est spécifié, le champ d'application du périmètre sera tous les périmètres importables. | EXPÉRIENCE |
Contenu de l'élément | |||
Si le mode est Saisie d'élément de paie ou Tout, il ne doit y avoir aucun sous-élément <périmètre>.
Si le mode est EXPLIQUE, il doit y avoir un ou plusieurs sous-éléments <périmètre>. Si le mode est EX facture, et si l'un des codes de périmètre d'un sous-élément <périmètre> n'est pas valide, l'élément <levels> (et par extension le périmètre <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 périmètre | |||
Nom du marqueur | level
Uniquement disponible dans API version 36 et supérieure | ||
Description | Indique le code du périmètre à inclure dans le périmètre de l'import.
Autorisé uniquement lorsque l'attribut mode de l'élément importDataOptions est Remplacer. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
includeDescendants | N | Si le périmètre est un périmètre parent, le fait d'indiquer un attribut égal à true (vrai) va inclure tous les descendants feuilles de ce périmètre, y compris lui-même (nœud uniquement) dans le périmètre.
Il s'agit d'un attribut facultatif. Si l'attribut n'est pas fourni, la valeur par défaut sera false (faux). Si l'attribut n'est pas fourni ou fournit la valeur false (faux) et que le périmètre spécifié est un périmètre parent, cela signifie que l'import ne prendra en compte que le nœud (par exemple, Ingénierie uniquement) de ce périmètre pour déterminer le périmètre. Les enfants du périmètre ne seront pas inclus dans le champ d'application, sauf indication explicite par d'autres éléments de périmètre. | vrai |
Contenu de l'élément | |||
Indique le code sensible à la casse du périmètre. Par exemple, <level>Développement/level>. En cas de problème avec le code du périmètre, par exemple un périmètre dont le code est introuvable, l'ensemble du périmètre <périmètre> et par extension le périmètre <Scope> 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 | time
Uniquement disponible dans API version 36 et supérieure | ||
Description | Indique une ou plusieurs plages de temps qui représentent le périmètre de temps de l'import.
Autorisé uniquement lorsque l'attribut mode de l'élément importDataOptions est Remplacer. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
mode | O | Indique le mode pour la période. Doit être l'une des trois options suivantes. Saisie d'élément de paie - lorsque ce mode est spécifié, la période sera déterminée par les codes de saisie des temps dans <header> élément. Si l'en-tête contient deux mois, alors le périmètre de l'import sera celui-ci.Expérience : si ce mode est spécifié, un ou plusieurs sous-éléments timeRange s'afficheront, qui détermineront l'intervalle de temps de l'import.VERSION : lorsque ce mode est spécifié, la période sera le début et la fin de la version, y compris toute période de solde initial.Si le mode est Saisie d'élément de paie 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. | SAISIE D'ÉLÉMENT DE PAIE |
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 API version 36 et supérieure | ||
Description | Indique une seule plage de temps pour la période.
Autorisé uniquement lorsque l'attribut mode de l'élément importDataOptions est Remplacer. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
début | O | Période de début de la plage de temps de l'import. | 07/2021 |
fin | O | Période de fin de la plage de temps de l'import. | 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 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 de période 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 alors séparés 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 réussie ou non des 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 | 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) | |||