Passer au contenu principal
Documentation
Documentation
Adaptive Planning
Dernière mise à jour : 2024-09-20
importStandardData

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
 

<?xml version='1.0' encoding='UTF-8'?>
<call method="importStandardData" callerName="a string that identifies your client application">
<credentials login="nobody@company.com" password="password" instanceCode="INSTANCE1"/>
<importDataOptions planOrActuals="Plan" allowParallel="true" moveBPtr="false" useMappings="false" mode="replace" />
<version name="Budget 2011" isDefault="false" />
<scope>
<accounts mode="explicit">
<account includeDescendants="false">30490</account>
<account includeDescendants="false">70313</account>
</accounts>
<levels mode="explicit">
<level includeDescendants="false">Development</level>
<level includeDescendants="true">Sales</level>
</levels>
<time mode="input" />
</scope>
<rowData>
<header>Account|Level|Split Label|Base Pay|CapitalAssetClass|Company|CountryRegion|01/2011</header>
<rows>
<row>30490|Asia Sales||120-150K|Furniture|ABC Cons|Washington|1</row>
<row>70313|Development||100-120K|OtherEquipment|ABC Cons|Maharashtra|2</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 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.
Ajouter
Les faits existants sont mis à jour ou de nouveaux faits sont ajoutés. Aucun fait ne sera supprimé.
Remplacer
La demande doit inclure un élément de champ d'application représentant les coordonnées de l' création hypercube dans laquelle les données seront remplacées par celles fournies dans les données utiles. Toutes les données existantes dans le périmètre et qui n'ont pas de coordonnées correspondantes dans les données utiles seront supprimées.
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 :
  • Code. Le contenu de l'élément de compte est un code de compte. Exemple :
    <account selector="code">30440</account>
    Dans cet exemple, 30440 est un code de compte.
  • Type. Le contenu de l'élément de compte est de type compte. Exemple :
    <account selector="type">GL</account>
    Dans cet exemple, le type d'élément de compte est tous les comptes GL. Actuellement, nous prenons uniquement en charge "GL" et "Customiser" comme type de compte pour les imports standard. Tous les autres résultats de contenu contiendront une erreur.
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
  1. Texte du message. Ce texte est exprimé dans la langue des paramètres régionaux indiqués dans la demande (en supposant que les paramètres régionaux soient pris en charge). Le texte peut également contenir des informations variables telles que le nombre de lignes qui ont été traitées ou la colonne ou la valeur particulière qui a généré une erreur.
  2. Un élément de contexte facultatif.
é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)