importTransactions
Catégorie | Soumission de données |
Description | Insère de nouvelles transactions. |
Autorisations obligatoires pour pouvoir être appelées | Importer |
Paramètres requis sur demande | Données d’identification, ImportTransactionsOptions, RowData |
Cette méthode s’applique uniquement si vous avez accès aux transactions.
Vous pouvez uniquement supprimer des transactions lors de l'importation. Si vous souhaitez supprimer toutes les transactions lors de l’importation, pensez à importer une rangée en blanc et à supprimer les données restantes.
Cette méthode peut être utilisée pour supprimer les rangées de transactions existantes qui correspondent à certains critères, pour insérer de nouvelles rangées de transactions dans le système ou pour effectuer les deux actions en une seule invocation (par exemple, remplacer un ensemble de rangées de transactions par un autre ensemble de rangées).
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 :
- données d'identification
- importTransactionsOptions
- rowData
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.
é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 numéros et les dates entrants et pour mettre en forme les numéros et les dates sortants (à l’aide du séparateur des milliers, des noms de mois et du format de date appropriés). 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 ImportTransactionsOptions | |||
Nom du marqueur | importTransactionsOptions | ||
Description | Indique les options à utiliser lors de l'importation. Si au moins une des valeurs suivantes est sélectionnéesupprimerStartDate,supprimerEndDate, outransactionTypes sont indiqués, alors cet appel de méthode tentera 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 certaines transactions existantes, cet attribut spécifie la date de début de l’ensemble des transactions à supprimer (incluant). Si elles ne sont pas précisées, toutes les transactions dont la date est identique ou antérieure à lasupprimerEndDate (et qui correspond à l’un des éléments facultatifs précisés)TransactionTypes) sera supprimé. | 11/01/2012 |
deleteEndDate | N | Si cet appel de méthode est destiné à supprimer certaines transactions existantes, cet attribut spécifie la date de fin de l’ensemble des transactions à supprimer (incluant). Si elles ne sont pas précisées, toutes les transactions dont la date est identique ou postérieure à lasupprimerStartDate (et qui correspondent à l’un des éléments facultatifs précisés)TransactionTypes) sera supprimé. | 12/31/2012 |
transactionTypes | N | Un ensemble de types de transactions qui seront supprimés, séparés par une barre verticale. Si non précisée, toutes les transactions données entresupprimerStartDate etsupprimerEndDate sera supprimé. Si nonsupprimerStartDate ousupprimerEndDate est précisé, toutes les transactions des types indiqués seront supprimées, quelle que soit leur date. | Bon de commande |
AllowParallel | Y | 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. | faux |
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. | faux |
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é. | faux |
displayNameEnabled
Disponible uniquement dans l’API v31+ pour les instances qui activent le nom d’affichage. | N | displayNameEnabled=true indique que l’API doit attendre les colonnes Code de compte, Code de niveau, Code de 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. afficherNameEnabled=false indique que l’API doit continuer à suivre le contrat d’API avant la version 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 « false ». | faux |
Contenu de l'élément | |||
(aucun) | |||
É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 | header | ||
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 mois qui peuvent 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 une importation réussie et non réussie des données sur les transactions.
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 | 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 |
header | Y | L’en-tête de la colonne. | "Compte" |
valeur | Y | La valeur dans la colonne. | "GL-29482-38233" |
Contenu de l'élément | |||
(aucun) | |||