Application de workflow XMLTODATABASE

Aperçu

L’application de workflow XMLTODATABASE vous permet d’exporter les données depuis un document XML vers une ou plusieurs bases de données. C’est une application asynchrone qui ne nécessite pas d’action d’un utilisateur. La configuration des transactions SQL est effectuée via un fichier XML qui active les requêtes SQL sur des sources de données ODBC ou OLEDB.

Mode de fonctionnement

Le moteur WorkflowGen appelle l’application XMLTODATABASE avec le contexte et les paramètres afin d’obtenir les éléments suivants :

  • Le document XML contentant les données à exporter

  • Le fichier de transaction contenant :

    • Les informations de connexion à la base de données

    • Les informations de localisation des données dans le document XML contenant les données (en utilisant des XPath)

Après que XMLTODATABASE ait rassemblé toutes ces informations, elle est prête à exporter, et retourne ensuite le contexte à WorkflowGen afin que le workflow puisse continuer.

Description du fichier XML

Aperçu

Le document de transactions XML spécifie les commandes SQL qui seront exécutées sur les bases de données. Il est utilisé pour deux fonctions principales: la connexion à la base de données et le mappage des champs de la requête aux champs du document de données XML. N'oubliez pas que le document de données XML (généralement nommé FORM_DATA) peut être construit de plusieurs façons. Pour cette raison, les XPath sont utilisés pour mapper les champs de base de données aux champs XML.

Structure

Toute activité XMLTODATABASE peut avoir un nombre illimité de bases de données et un nombre illimité de commandes par base de données. Cela signifie que l'exportation peut être effectuée vers plusieurs bases de données et que chaque base de données peut avoir plusieurs commandes.

Voici un exemple de fichier de transaction :

<transactions>
    <transaction name="">
        <databases>
            <database name="" connectionstring="" provider="" transaction="">
                <command type="" loop="" xpath="">
                [REQUÊTE ICI]
                </command>
            </database>
        </databases>
    </transaction>
</transactions>

Attributs

Nœud transaction

Nœud database

  • Vous pouvez utiliser l'attribut connectionstringname ou l'attribut connectionstring, mais pas les deux.

  • Il est fortement recommandé d'utiliser un nom de connexion plutôt qu'une chaîne de connexion pour simplifier la gestion multi-environnement.

Nœud command

Exemple de nom de chaîne de connexion

Fichier de transactions XMLTODATABASE :

...
<database name="MYDB" connectionstringname="MYDBSOURCE">
..

Fichier web.config :

..
<connectionStrings>
    <add name="MYDBSOURCE" connectionString="Data Source=MYSQLSERVER;Initial Catalog=MYDB;User ID=user;password=pwd;" providerName="System.Data.SqlClient"/>
<connectionString>
...

Emplacement du fichier XML de transactions

Il y a quatre possibilités différentes pour stocker la définition de la transaction d’une action de type XMLTODATABASE. Dans tous ces cas, la transaction doit être définie ainsi :

<transactions>
    <transaction name="MY_TRANSACTION">
        ...
    </transaction>
</transactions>

Pour trouver la définition de sa transaction une action de type XMLTODATABASE va effectuer une recherche dans l’ordre suivant :

  1. Dans un paramètre nommé TRANSACTIONS_TEXT.

  2. Dans un fichier dont le chemin est dans un paramètre nommé TRANSACTIONS_FILE.

  3. Dans un fichier nommé MyTransaction.xml placé dans le dossier ..\App_Data\Files\XmlToDatabase.

  4. Dans un fichier nommé Transactions.xml placé dans le dossier ..\App_Data\Files\XmlToDatabase.

L’ordre de priorité est donc :

  1. Le paramètre TRANSACTIONS_TEXT.

  2. Le paramètre TRANSACTIONS_FILE.

  3. Le fichier MyTransaction.xml.

  4. Le fichier Transactions.xml.

Définition d’une transaction dans le fichier commun

Le fichier de transaction commun nommé Transactions.xml se trouve dans le répertoire \wfgen\App_Data\Files\XmlToDatabase. L’application XMLTODATABASE effectue une recherche dans ce fichier pour trouver votre transaction.

L’action de type XMLTODATABASE contient les paramètres suivants :

  • TRANSACTION : Direction IN, type texte

  • XML : Direction IN, type fichier

Définition d’une transaction dans un fichier spécifique

Si la transaction ne se trouve pas dans le fichier Transactions.xml, l’application XMLTODATABASE effectue une recherche pour un fichier XML du même nom que votre transaction. La transaction devrait être créée dans le fichier MyTransaction.xml.

L’action de type XMLTODATABASE a les mêmes paramètres que pour un fichier commun.

Vous pouvez déplacer la définition de transaction d’un fichier commun à un fichier spécifique sans avoir à modifier la définition de processus en supprimant la transaction du fichier Transactions.xml et ensuite le copier dans un fichier du même nom que votre transaction.

Dans une donnée de type fichier

Si vous ne pouvez pas accéder au dossier ..\App_Data du serveur Web, ou si vous souhaitez inclure votre transaction dans la définition de votre processus (pour pouvoir l’exporter et le partager par fichier XPDL), vous pouvez écrire votre transaction dans une donnée de type fichier de votre processus. Pour ce faire :

  1. Créez une donnée de type fichier contenant votre transaction.

  2. Éditez votre action de type XMLTODATABASE puis ajoutez un nouveau paramètre nommé TRANSACTIONS_FILE et liez-le à la donnée précédemment créée.

Dans une donnée de type texte

Si vous ne pouvez pas accéder au dossier ..\App_Data du serveur Web, ou si vous souhaitez inclure votre transaction dans la définition de votre processus (pour pouvoir l’exporter et le partager par fichier XPDL), vous pouvez écrire votre transaction dans une donnée de type texte de votre processus.

À partir de la version 7.15.0 de WorkflowGen, la transaction XML contenue dans les données de processus de type TEXT n'a plus de limite de 4 000 caractères pour la base de données MS SQL Server.

Pour ce faire :

  1. Créez une donnée de type texte contenant votre transaction.

  2. Éditez votre action de type XMLTODATABASE puis ajoutez un nouveau paramètre nommé TRANSACTIONS_TEXT et liez-le à la donnée précédemment créée.

Format des champs dates et numériques

Vous pouvez indiquer à l’application la liste des champs qui doivent avoir un format date ou numérique.

Les paramètres supplémentaires suivants peuvent être utilisés dans les actions qui utilisent XMLTODATABASE:

Format date généré dans les requêtes SQL

Les champs de type date sont formatés comme ci-après : yyyy-mm-dd hh:MM:ss

Format numérique généré dans les requêtes SQL

Les champs de type numérique sont formatés comme ci-après : XXXX.XX

Exemple :

  • Règle : Tous les nœuds trouvés dans le document XML avec le nom REQUEST_DATE et le nœud spécifique situé à /MyData/MyExemple/Champ_Date seront formatés comme des dates.

  • Méthode : XML_FIELDS_DATE = //*/REQUEST_DATE, /MyData/MyExample/Date_Field

Détails de l’exécution de la transaction

Les commandes SQL peuvent être exécutées dans des transactions. Si des erreurs interviennent, un « rollback » est exécuté et l’état initial de la base de données est restauré. La valeur de l’attribut transaction du nœud database doit être réglée sur yes.

Si la transaction agit sur plusieurs bases de données, l’exécution des commandes sera multi-transactionnelle : si une erreur intervient dans une commande d’une des bases de données, une restauration générale sera exécutée sur la transaction en question.

Mode test

Les transactions peuvent être testées avant d’être lancées sur les bases de données. La valeur de la constante XmlToDatabaseTestMode dans le fichier de configuration doit être réglée sur Y.

Si cette constante est définie sur yes et que vous avez spécifié l’usage des transactions sur les nœuds de la base de données, les transitions ne seront pas confirmées (committed) à la fin de l’exécution.

Description du fichier log

Si le paramètre XmlToDatabaseEnableTrace dans le fichier web.config du service Web est réglé sur Y, un fichier de log sera généré dans le répertoire \wfgen\App_Data\LogFiles\XmlToDatabase.

Les entrées du log sont au format suivant :

Date; [Database name;] Transaction name; SQL query; Execution result

Les valeurs execution result sont :

  • Si la requête a été exécutée avec succès : OK

  • Si une erreur est intervenue : ERROR : code erreur – description

Exemples :

02/12/2020 4:41:23 PM; ACCESS; TEST_TRANS; INSERT INTO DATA ...; OK
02/12/2020 4:41:24 PM; ACCESS; TEST_TRANS; DELETE FROM DATA2; ERROR: 1234-Table was not found

Erreurs d’exécution possibles

Les erreurs suivantes peuvent intervenir lors de l’exécution des transactions :

Exemples d’export

Exemple 1

Structure du fichier XML :

<data>
    <request_number>1</request_number>
    <request_first_name>John</request_first_name>
    <request_last_name>Smith</request_last_name>
</data>

Le nœud command pourrait ressembler à ceci :

<command type="INSERT" loop="no" xpath="/data/">
    INSERT INTO EXAMPLE (request_number, request_first_name, request_last_name, request_date)
    VALUES (
        {XPATH:request_number},
        {'XPATH:request_first_name'},   
        {'XPATH:request_last_name'},
        {'PARAM:REQUEST_DATE'})
</command>

La balise XPATH: dans la requête sera remplacée par /data/ qui est la valeur de l’attribut XPath.

La balise PARAM: est utilisée pour identifier un paramètre WorkflowGen à la place d’utiliser un champ XML.

  • Les XPath ne retournant pas de nœuds utiliseront les valeurs null.

  • Il n’est pas possible d’utiliser le XPath factorisé en utilisant XPATH:: à la place de XPATH:.

Exemple 2

Voici un exemple plus complexe utilisant la propriété loop.

Structure du fichier XML :

<Library>
    <publishers>
        <publisher>Grasset</publisher>
    </publishers>
    <AUTHORS>
        <author id="100">
            <name>Stephen King</name>
            <description>Auteur de livres d’horreur</description>
            <birth_date>1947-09-21</birth_date>
        </author>
        <author id="200">
            <name>Jean Sologne</name>
            <description>Description de l’auteur</description>
            <birth_date>1972-06-06</birth_date>
        </author>
    </AUTHORS>
    <BOOKS>
        <book id="38">
            <title>Titre du livre no°38</title>
            <description>Description du livre n°38</description>
            <author id="100"/>
        </book>
        <book id="39">
            <title>Titre du livre n°39</title>
            <description>Description du livre n°39</description>
            <author id="200"/>
        </book>
        <book id="40">
            <title>Titre du livre n°40</title>
            <description />   // Insérera une valeur NULL automatiquement</span>
            <author id=""/>   // Insérera une valeur NULL automatiquement</span>
        </book>
    </BOOKS>
</Library>

Le nœud command pourrait ressembler à ceci :

<command loop="yes" type="INSERT" xpath="/Library/AUTHORS/">
    INSERT INTO AUTHORS
        ([AUTHOR_ID],[AUTHOR_NAME],[AUTHOR_DESC],[AUTHOR_PUBLISHER])
    VALUES ({XPATH:author/@id},
        '{XPATH:author/name}',
        '{XPATH:author/description}',
        '{XPATH::/Library/publishers/publisher}’ )
</command>
<command loop="yes" type="INSERT" xpath="/Library/BOOKS/">
    INSERT INTO BOOKS 
        ([BOOK_ID],[BOOK_TITLE],[BOOK_DESCRIPTION],[BOOK_AUTHOR_ID])
    VALUES ({XPATH:book/@id},
        '{XPATH:book/title}',
        '{XPATH:book/description}',
        '{XPATH:book/author/@id}')
</command>

Vous devez utiliser deux caractères : (deux points) lorsque vous ne voulez pas utiliser le XPath factorisé dans le nœud command (voir l’exemple ci-dessus).

Dernière mise à jour