importTransactions
Catégorie | Soumission de données |
Description | Insère de nouvelles transactions. |
Autorisations requises pour appeler | Importer |
Paramètres obligatoires à la demande | Identifiants, ImportTransactionsOptions, RowData |
Cette méthode s'applique uniquement si vous avez accès au périmètre Transactions.
Vous pouvez uniquement supprimer des transactions pendant l'import. Si vous souhaitez supprimer toutes les transactions pendant l'import, pensez à importer une ligne vide et à supprimer les données restantes.
Cette méthode peut être utilisée pour supprimer les lignes de transactions existantes dont les critères correspondent à certains critères, pour insérer de nouvelles lignes de transactions dans le système ou pour effectuer les deux actions en une seule invocation (c'est-à-dire remplacer un ensemble de lignes de transactions par un autre ensemble de lignes).
Format de demande
<?xml version='1.0' encoding='UTF-8'?> <call method="importTransactions" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <importTransactionsOptions allowParallel="false" useMappings="false"/> <rowData> <header>Posting Date|Transaction Type|Account|Plan|Transaction Amount</header> <rows> <row>01/02/2011|Invoice|70110|Marketing|100</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
- importTransactionsOptions
- rowData
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.
é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 des milliers, les noms de mois et la mise en forme de date appropriés). 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 importTransactionsOptions | |||
Nom du marqueur | importTransactionsOptions | ||
Description | Indique les options à utiliser lors de l'import. Si au moins l'une des valeursdeleteStartDate,deleteEndDate, outransactionTypes sont indiqués, cet appel de méthode va essayer de supprimer toutes les transactions existantes qui correspondent aux critères indiqués. | ||
Attributs de l'élément | |||
Nom de l'attribut | Obligatoire ? | Valeur | Exemple |
deleteStartDate | N | Si cet appel de méthode est destiné à supprimer des transactions existantes, cet attribut indique la date de début de l'ensemble de transactions à supprimer (inclus). Si aucune date n'est indiquée, toutes les transactions dont la date est identique ou antérieure audeleteEndDate (et qui correspond à l'une des valeurs facultatives indiquéesTransactionTypes) sera supprimé. | 11/01/2012 |
deleteEndDate | N | Si cet appel de méthode est destiné à supprimer des transactions existantes, cet attribut indique la date de fin de l'ensemble de transactions à supprimer (inclus). Si aucune date n'est indiquée, toutes les transactions dont la date est identique ou postérieure à la datedeleteStartDate (et qui correspondent à l'une des valeurs facultatives indiquéesTransactionTypes) sera supprimé. | 12/31/2012 |
transactionTypes | N | Un ensemble de types de transaction qui seront supprimés, séparés par le symbole du trait vertical. Si aucune option n'est indiquée, toutes les transactions comprises entredeleteStartDate etdeleteEndDate va être supprimé. Si nondeleteStartDate oudeleteEndDate est indiqué, toutes les transactions des types indiqués seront supprimées, quelles que soient leurs dates. | Bon de commande |
AllowParallel | O | 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 v31 et supérieure pour les instances qui activent le nom d'affichage. | N | displayNameEnabled=true indique que l'API doit rechercher les colonnes Code du compte, Code du périmètre, Code de la dimension et Nom de la dimension dans les données utiles lorsque le paramètre Activer le nom d'affichage est activé pour l'instance. displayNameEnabled=false indique que l'API doit continuer après le contrat API pré-v30, même lorsque le paramètre Activer le nom d'affichage est activé pour l'instance. La valeur par défaut pour displayNameEnabled est "faux". | false |
Contenu de l'élément | |||
(aucun) | |||
É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 | header | ||
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 mois 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 transaction.
Exemple de réussite
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <messages> <message key="row-imported">1 row was imported.</message> </messages> </response>
Échec (avec contexte)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-import">Import Failed with the following error: No transactions were imported or deleted during the import.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Transaction Type do not exist: Invoice12.</message> <message key="invalid-dimension-choice-withCoordinate"> <context> <col header="Posting Date" value="01/02/2011" /> <col header="Transaction Type" value="Invoice12" /> <col header="Account" value="70110" /> <col header="Plan" value="Marketing" /> <col header="Transaction Amount" value="100.0" /> </context> Invalid Dimension Choice: Invoice12 on row 1 column B </message> </messages> </response>
Échec (sans contexte)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-import">Import Failed with the following error: No transactions were imported or deleted during the import.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Transaction Type do not exist: Invoice12.</message> <message key="invalid-dimension-choice-withCoordinate">Invalid Dimension Choice: Invoice12 on row 1 column B</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 messages | |||
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-attributevalueid |
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 |
header | O | L'en-tête de la colonne. | "Compte" |
valeur | O | Valeur de la colonne. | "GL-29482-38233" |
Contenu de l'élément | |||
(aucun) | |||