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

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+
<?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 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.
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 qui représente les coordonnées de l’URLterube dans lequel les données seront remplacées par celles fournies dans les données utiles. Toutes les données existantes dans le champ d'application qui n'ont pas de coordonnée correspondante dans la charge utile seront supprimées.
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 :
  • 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 un type de 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 en charge uniquement « GL » et « CUSTM » pour le type de compte pour les importations standard. Tout autre contenu donne des résultats erronés.
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
  1. Le texte du message. Ce texte est dans la langue des paramètres régionaux indiqués dans la demande (en supposant que les paramètres régionaux sont pris en charge). Le texte peut également contenir des renseignements variables, tels que le nombre de rangées traitées, ou la colonne ou la valeur particulière qui a causé 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 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)