Aller à : navigation, rechercher

Maarch Courrier/latest/fr/Tutorials/Creer web service

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 via web services. Cette application permet d'ajouter, consulter et faire une recherche parmi les factures du SAE Maarch, 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 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 via web services dans d'autres langages de développement (JAVA, .NET, Python, ...).

Accueil appliComptable.png

Fonctionnalités initialement présentes

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


MENUHighlight.png

Web service à ajouter

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


MENUHighlightRecherche.png

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 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 doit être installé, si ce n'est pas fait, suivez d'abord le tutoriel d'installation de Maarch.
  • 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 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 .


  • 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.

Ws clientAdresse.png

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

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

VerserForm.png


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 ».


VerserFini.png


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;
  • « 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.

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.


StoreResource.png

[ La fonction storeResource dans le WSDL ]


ArrayOfData.png

[ 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 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

ConsulterForm.png


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.


Consultation.png


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


ViewResource.png


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.


ReturnViewResource.png


  • « 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

Par principe dans Maarch, 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, 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.


Fonction storeResource.png

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

ReturnViewResource.png

[ Déclaration du tableau complexe returnViewResource ]

ViewResource.png

[ 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 » :


WsDeRecherche.png


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.

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)


FonctionDemo searchResources.png


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 (bblier/maarch par exemple), c'est ici que vous trouvez la liste des web services Maarch. Vous devriez y retrouvez le nouveau web services de recherche que nous venons d'ajouter. Le WSDL correspond à un catalogue de fonctions.


WSDLDemo.png


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.


RechercherForm.png


$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 );


RechercherResult.png


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 et créer les vôtres !

Intégrer votre outil d'emailing à Maarch

Un autre exemple d'intégration d'une application métier à Maarch 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 via web services. Vous bénéficiez ainsi de la base de contacts Maarch enrichie par le versement des courriers entrants.