Tutoriel sur les web services

De Maarch // Wiki.

Sommaire 1 Présentation du tutoriel 2 Fonctionnalités initialement présentes 3 Web service à ajouter 4 Comment installer l'application comptable 5 Étude de l'intégration du versement de factures depuis l'application comptable 6 Étude de l'intégration de la consultation de factures depuis l'application comptable 7 Ajout d'un web service dans Maarch Entreprise 8 Intégrer votre outil d'emailing à Maarch Entreprise

Présentation du tutoriel

Pour présenter les web services Maarch nous avons choisi de créer une application métier de comptabilité reliée à Maarch Entreprise via web services. Cette application permet d'ajouter, consulter et faire une recherche parmi les factures du SAE Maarch Entreprise, le tout via web services.

Pas à pas nous allons dans ce tutoriel recréer cette application qui utilise des fonctionnalités déjà présentes dans les web services Maarch Entreprise et en créer une nouvelle.

La documentation technique sur les web services Maarch est accessible sur notre ce wiki : Interopérabilité par Web Services.

Le client de web services est écrit en PHP pour ce tutoriel mais vous pouvez bien entendu, vous interconnecter avec Maarch Entreprise via web services dans d'autres langages de développement (JAVA, .NET, Python, ...).

Fonctionnalités initialement présentes

Le versement et la consultation utilisent des fonctionnalités web services initialement présentes dans Maarch Entreprise.

Web service à ajouter

La fonction permettant de faire des recherches parmi les factures via web service n'est pas présente initialement dans Maarch Entreprise mais nous allons la créer ensemble. Le but étant d'être capable par la suite d'ajouter vos propres web services à Maarch Entreprise.

Comment installer l'application comptable

Avant de commencer nous allons vérifier que tous les prérequis nécessaires à l'utilisation des web services sont réunis. Le tutoriel peut tourner sur Windows et Linux, les exemples de commandes sont pour Ubuntu/Debian. Maarch Entreprise et l’application comptable peuvent bien entendu être installés sur deux serveurs distincts. Pour simplifier le tutoriel ils seront installés sur la même machine.

• Maarch Entreprise doit être installé, si ce n'est pas fait, suivez d'abord le tutoriel d'installation de Maarch Entreprise.

• Lire la documentation sur les web services Maarch Entreprise : Interopérabilité par Web Services

• PHP doit être installé sur le serveur hébergeant l’application comptable 
  • Installation de php5 et Apache2:

$ sudo apt-get install php5
$ sudo apt-get install apache2

• Maintenant que PHP est installé, nous allons installer PEAR :
  • Installation de php-pear :

$ sudo apt-get install php-pear

• Ajoutons SOAP à PEAR :
  • Installation de SOAP :

$ sudo pear install SOAP-0.12.0

• Créer un espace de stockage Maarch Entreprise pour les factures versées dans le SAE via web service. Dans votre dossier « entreprise » du dossier « docservers »,  créez un dossier « web_services ».

• Il faut maintenant indiquer à la base de données que les factures versées seront stockées dans le dossier que vous venez de créer.

Pour cela, vous devez exécuter cette requête SQL en prenant soin de modifier l'adresse du dossier « web_services » :

INSERT INTO docservers (docserver_id, docserver_type_id, device_label, is_readonly, enabled, size_limit_number,
actual_size_number, path_template, ext_docserver_info, chain_before, chain_after, creation_date, closing_date, 
coll_id, priority_number, docserver_location_id, adr_priority_number) VALUES ('WEB_SERVICES', 'FASTHD', 
'zone de stockage pour les web services', 'N', 'Y', 100000000000, 109202,
'/var/docservers/entreprise/web_services/', NULL, NULL, NULL, '2011-10-17 18:39:17.573393', NULL, 'res_coll', 1,
'NANTERRE', 6);

• Vous êtes maintenant prêt à utiliser les web services Maarch Entreprise.

• Vous pouvez télécharger l'application comptable de démonstration depuis notre svn :

$ svn co http://svn.maarch.org/tool_box/trunk/WS_Sample/ path_to_apache_root

Pour installer l'application comptable sur votre machine, vous devez placer le dossier « WS_Sample Â» à la racine de votre serveur web (/var/www/ sur Linux et c:\xampp\htdocs\ sur windows).

Vous devez ensuite personnaliser le fichier « ws_client.php » du dossier « WS_Sample Â» afin que l'application comptable communique avec Maarch Entreprise.

Modifiez l'adresse surlignée en fonction de votre installation de Maarch Entreprise.

L'application est ensuite fonctionnelle et accessible depuis l'adresse, http://127.0.0.1/WS_Sample/

Étude de l'intégration du versement de factures depuis l'application comptable

Pour l'utilisateur, le versement d'une facture se résume à :

• Choisir une facture sur son ordinateur depuis le bouton « Choisissez une facture » ;
• Entrer l'objet de le facture dans le champ « Objet » ;
• Entrer le pays dans le champ « Pays » ;
• Puis valider le formulaire en cliquant le boutant « Ajouter ».

Une fois le formulaire validé, la page de confirmation du versement s'affiche, indiquant que la facture a été enregistrée sous l'identifiant XXX. Un lien permet d'afficher de suite cette facture dans l'application.

Techniquement, le versement d'une facture utilise la fonction « storeResource »

Cette fonction prend (Request) en paramètre :

• « encodedFile », une chaîne de caractères (string) contenant la facture à ajouter encodée en base64;
• « data », un tableau complexe (complex) sur lequel nous reviendrons juste après ;
• « collId » une chaîne de caractères (string) contenant le nom de la collection Maarch Entreprise ;
• « table » une chaîne de caractères (string) contenant le nom de la table servant à faire l'enregistrement SQL ;
• « fileFormat » une chaîne de caractères (string) contenant l'extension de la facture ;
• « status » une chaîne de caractère (string) permettant d'indiquer si la facture enregistrée est nouvelle, en attente, … dans Maarch Entreprise.

Et elle renvoie (Response) :

• « out » une chaîne de caractères (string) contenant l'identifiant d'enregistrement de la facture dans la table.

Revenons sur « data » ; Comme vu précédemment, « data » est un objet complexe (tableau de tableau) qui renvoie à « arrayOfData » qui lui-même renvoi à « arrayOfDataContent », un autre objet complexe.

[ La fonction storeResource dans le WSDL ]

[ La déclaration de tableaux complexes ]

« arrayOfDataContent » prend en paramètre :

• « column » une chaîne de caractère (string) qui contient le nom d'une colonne de la table res_x ;
• « value » une chaîne de caractère (string) qui contient la valeur à insérer dans la table res_x pour la colonne choisit dans le paramètre « column »
• « type » une chaîne de caractère (string) qui contient le type de « value ».

Prenons un exemple concret, nous voulons ajouter une facture « pdf » de « France » que l'on nommera « Facture_1 », elle sera dans la collection « res_coll », la table « res_x », et sous le statut nouveau « NEW ».

Il faut alors que « storeResource » reçoive :

'encodedFile' : « la facture encodée en base64 »
'data' [ 
    'arrayOfDataContent' [ 
        'column' : 'subject',
        'value' : 'Facture_1',
        'type' : 'string',
    ]
    arrayOfDataContent [
        'column' : 'custom_t3', //La colonne « pays »
        'value' : 'France',
        'type' : 'string',
    ]
    arrayOfDataContent [
        'column' : 'doc_date',  //La colonne « date »
        'value' : '2011-10-18 15:29:33',
        'type' : 'string',
    ]
    arrayOfDataContent [
        'column' : 'type_id',
        'value' : '70'  ,       //L'identifiant des factures
        'type' : 'string',
    ]
]
'collId' : 'res_coll'
'table' : 'res_x'
'fileFormat' : 'pdf'
'status' : 'NEW'

La correspondance des champs custom avec le métier des factures est disponible depuis le fichier de paramétrage de Maarch Entreprise suivant : chemin_vers_maarch_entreprise/maarch_entreprise/apps/maarch_entreprise/xml/index_invoices.xml

Étude de l'intégration de la consultation de factures depuis l'application comptable

Pour l'utilisateur, la consultation d'une facture nécessite :

• d'entrer l'identifiant dans le champ « ID de la facture » ;
• puis de valider le formulaire en cliquant sur le bouton « Voir la facture ».

Il n'est pas évident que l'on connaisse à l'avance l'identifiant Maarch de la facture que l'on veut consulter, c'est pourquoi par la suite on va créer un web service de recherche.

Techniquement, la consultation d'une facture utilise la fonction « viewResource »

Cette fonction prend (Request) en paramètre :

• « getId » un entier (integer) qui est l'identifiant de la facture à consulter ;
• « tableName » une chaîne de caractères (string) qui est le nom de la table ou sont enregistrées les infos sur la facture;
• « adrTableName » une chaîne de caractère (string) qui est la table d’adressage du document sur plusieurs espaces de stockage.
• « calledByWs » un booléen (boolean) qui doit être à « true » dans le cas des web_services ;

Elle renvoie (Response) :

• « out » le tableau complexe « returnViewResource » détaillé juste après.

Revenons sur « out » ; « out » est un tableau complexe qui renvoie vers « returnViewResource » qui lui contient différentes informations sur la facture à afficher.

• « status » une chaîne de caractères (string) qui contient une indication sur l'exécution de la fonction ;
• « mime-type » une chaîne de caractères (string) qui contient le type MIME du fichier de la facture ;
• « ext » une chaîne de caractères (string) qui contient l'extension du fichier ;
• « file_content » une chaîne de caractères (string) qui contient le fichier encodé en base64 ;
• « tmp_path » une chaîne de caractères (string) qui contient le chemin temporaire du fichier ;
• « file_path » une chaîne de caractères (string) qui contient le chemin du fichier ;
• « called_by_ws » une chaîne de caractères (string) qui contient « true » dans le cas des web services ;
• « error » une chaîne de caractères (string) qui contient la ou les déclarations d'erreurs s'il y en a eu.

Exemple : On veut consulter la facture d'ID « 409 » de la table « res_x » par web service « true ».

« viewResource » doit alors recevoir :

'getID' : '409'
'tableName : 'res_x'
'adrTableName' : 'adr_x'
'calledByWS' : 'true'

Qui va alors renvoyer :

'out' [ 
    'status' : 'ok'
    'mime-type' :  'application/pdf'
    'ext' : 'pdf'
    'file_content' : « le fichier encodé »
    'tmp_path' : « le chemin »
    'file_path' : 
    'called_by_ws' : 'true'
    'error' : 
]

Ajout d'un web service dans Maarch Entreprise

Par principe dans Maarch Entreprise, toutes les fonctions comprises dans les contrôleurs d’objets (exemple : docservers_controler.php) sont appelables via web services. Pour déclarer un web service Maarch il faut se servir des fichiers ws.php. Il existe plusieurs « ws.php » dans Maarch entreprise, nous allons travailler dans « maarch_entreprise/core/class/ws.php ». Ouvrez ce fichier, vous constatez que les déclarations de fonctions et des tableaux complexes sont dans ce fichier. Toutes les fonctions utilisables par web services doivent posséder leur « dispatch_map » ainsi que ses déclarations associées dans « ws.php », le dispatch_map correspond à la signature de la fonction.

[ Déclaration des tableaux complexes et de la dispatch_map de la fonction storeResource ]

[ Déclaration du tableau complexe returnViewResource ]

[ dispatch_map de la fonction viewResource ]

Par exemple ici on voit que la fonction viewResource prend en paramètre 4 champs (gedId, tableName, adrTableName, calledByWS) et renvoie un objet complexe défini par le tableau returnViewResource. On va maintenant ajouter la fonction et les déclarations nécessaires pour créer le web service de recherche. Toujours dans le fichier « maarch_entreprise/core/class/ws.php Â», on va se placer à la fin et ajouter :

• la déclaration du tableau complexe « searchParams », qui sont les critères de recherche.

$SOAP_typedef['searchParams'] = array(
    'country' => 'string',
    'docDate' => 'date',
);

• la déclaration du tableau complexe « listOfResources », qui est la liste des factures trouvées que renverra le web service de recherche.

$SOAP_typedef['listOfResources'] = array(
    'resid' => 'long',
    'identifier' => 'string',
    'contactName' => 'string',
    'country' => 'integer',
    'amount' => 'string',
    'customer' => 'string',
    'docDate' => 'string',
);

• la déclaration du tableau complexe « docListReturnArray », qui est l’objet complexe renvoyé par le web service.

$SOAP_typedef['docListReturnArray'] = array(
    'status'=>'string',
    'value'=>'{urn:MySoapServer}listOfResources',
    'error'=>'string',
);

• le « dispatch_map » de la fonction de recherche Demo_searchResources, qui correspond donc à la signature de la fonction. Le web service prend en paramètre l’objet complexe searchParams et renvoie l’objet complexe docListReturnArray.

$SOAP_dispatch_map['Demo_searchResources'] = array(
    'in' => array(
        'searchParams' => '{urn:MySoapServer}searchParams',
    ),
    'out' => array(
        'out' => '{urn:MySoapServer}docListReturnArray',
    ),
    'method' => "core#resources::Demo_searchResources",
) ;

Vous devriez donc avoir à la fin de votre « ws.php » :

On voit que les « dispatch_map » des fonctions ont tous le même squelette, « in » « out » et « method ».

• « in » correspond aux paramètres que la fonction va devoir recevoir (Request) ;
• « out » correspond aux paramètres que la fonction va renvoyer (Response) ;
• « method » est l'emplacement de la fonction.

Dans le cas de notre web service de recherche, « method » a pour valeur « core#resources::Demo_searchResources ». Cela signifie que la fonction de recherche « Demo_searchResources » se trouve dans le fichier « resources_controler » du dossier « core/class » de l'application Maarch Entreprise.

On va donc ouvrir ce fichier « maarch_application/core/class/resources_controler.php ». Allez à la fin de ce fichier, c'est ici que l'on va créer notre fonction de recherche « Demo_searchResources » Ajoutez avant la dernière accolade fermante « } »:

function Demo_searchResources($searchParams)
{
    $whereClause = "";
    if ($searchParams->countryForm <> "") {
        $whereClause .= " custom_t3 = '" . $searchParams->countryForm . "' and ";
    }
    if ($searchParams->docDateForm <> "") {
        $whereClause .= " doc_date >= '" . $searchParams->docDateForm . "'";
    }
    $listResult = array();
    try {
        $db = new dbquery();
        $db->connect();
        $cpt = 0;
        $db->query("select * from res_x where " . $whereClause . " ORDER BY res_id ASC");
        if ($db->nb_result() > 0) {
            while ($line = $db->fetch_object()) {
                $listResult[$cpt]['resid'] = $line->res_id;
                $listResult[$cpt]['subject'] = $line->subject;
                $listResult[$cpt]['docdate'] = $line->doc_date;
                $cpt++;
            }
        } else {
            $error = _NO_DOC_OR_NO_RIGHTS;
        }
    } catch (Exception $e) {
        $fault = new SOAP_Fault($e->getMessage(), '1');
        return $fault->message();
    }
    $return = array(
        'status' => 'ok', 
        'value' => $listResult,
        'error' => $error,
    );
    return $return;
}

Vous devriez donc avoir : (ce qui a été rajouté, est surligné en violet ; le reste était déjà présent)

Maintenant que la fonction est écrite dans le fichier resources_controler.php et que les dispatch_map et les déclarations sont dans le ws.php. Ouvrez la page http://127.0.0.1/maarch_entreprise/ws_server.php?WSDL Après avoir entré un nom d'utilisateur et un mot de passe d’un utilisateur Maarch Entreprise (bblier/maarch par exemple), c'est ici que vous trouvez la liste des web services Maarch entreprise. Vous devriez y retrouvez le nouveau web services de recherche que nous venons d'ajouter. Le WSDL correspond à un catalogue de fonctions.

Si vous êtes arrivé ici, alors le plus dur est fait. Notre nouvelle fonction est créée, il nous reste plus qu'à l'appeler.

Pour appeler cette fonction, il faut lui passer un paramètre. Ce paramètre est un tableau ($searchParams) contenant deux entrées correspondantes aux deux critères de recherches. Le premier est le pays ($countryForm) de la facture et le second la date limite inférieure ($docDateForm) de versement de la facture.

$searchParams = array(
    "countryForm" => $countryForm,
    "docDateForm" => $docDateForm
);

Dans notre application, $countryForm et $docDateForm récupèrent les valeurs du formulaire via :

$countryForm = $_REQUEST['countryForm'] ;
$docDateForm = $_REQUEST['docDateForm'] ;

Maintenant que l'on a toutes les données de recherche, on envoie à la fonction :

$searchResource = $client->Demo_searchResources($searchParamsForm );

Le résultat de la recherche se trouve alors dans le tableau complexe : $searchResult

Vous êtes maintenant prêt pour utiliser les web services Maarch Entreprise et créer les vôtres !

Intégrer votre outil d'emailing à Maarch Entreprise

Un autre exemple d'intégration d'une application métier à Maarch Entreprise est disponible :

$ svn co http://svn.maarch.org/tool_box/trunk/WS_Sample/ws_client_contacts.php path_to_apache_root

Cet exemple vous montre comment intégrer votre outil d'emailing à Maarch Entreprise via web services. Vous bénéficiez ainsi de la base de contacts Maarch enrichie par le versement des courriers entrants.