Introduction Installation Configuration Principes de fonctionnement Configuration des principaux modules FileImport MailCapture MaarchWSClient Modèles de configuration Déploiement de la configuration pour une instance de Maarch Courrier Procédures d'exploitation de Maarch Capture

MaarchWSClient

MaarchWSClient est un module permettant de transférer dans MaarchCourrier les documents traités par MaarchCapture.

Il utilise les protocoles SOAP ou REST pour verser les documents via webservice.

Paramétrage général du module

Depuis le fichier de paramétrage général : ./config/Capture.xml.

<step name="SendToMaarch" module="MaarchWSClient" function="processBatch">
    <input name="WS">MaarchRestWS</input>
    <input name="Process">MaarchRestWSProcessFromMail</input>
    <input name="CatchError">true</input>
    <input name="configFile">MaarchWSClient_standard_sample.xml</input>
</step>

La déclaration du module comporte les attributs suivants :

WS identifiant de la déclaration du frontal webservice utilisé dans le fichier configFile du module MaarchWSClient. Ex : pour le protocole REST nous avons dans le jeu de démo la déclaration du WS MaarchRestWS. Pour le protocole SOAP MaarchSoapWS.
Process identifiant global des webservices à utiliser pour la communication avec l’application cible (dépendant de l’id WS utilisé). Ex : pour le protocole REST nous avons dans le jeu de démo la déclaration du process MaarchRestWSProcessFromMail. Pour le protocole SOAP MaarchSoapWSProcessFromMail.
CatchError Flag pour indiquer si on doit lever une exception si une erreur de communication par webservice est détectée. Cela permet de ne pas bloquer tout le processus de versement dans l’application cible si une erreur est détectée. Prend true ou false comme valeur.
configFilenom du fichier de configuration définissant les webservices pour communiquer avec l’application cible. Le nom du fichier défini doit se trouver dans le répertoire ./modules/MaarchWSClient/.

Paramétrage particulier des webservices

Depuis le fichier de paramétrage de la boite mail à capturer : ./modules/MaarchWSClient/MaarchWSClient_standard_sample.xml.

<?xml version="1.0" encoding="UTF-8"?>
<MaarchWSClient>
    <!-- REST FRONTAL -->
    <WS name="MaarchRestWS" type="REST" uri="http://superadmin:superadmin@127.0.0.1/MaarchCourrier/rest/" />
    <!-- SOAP FRONTAL -->
    <WS name="MaarchSoapWS" type="SOAP" uri="http://127.0.0.1/MaarchCourrier/ws_server.php?WSDL" SSL="false" cacheUse="0" >
        <proxy>
            <user>superadmin</user>
            <pass>superadmin</pass>
            <timeout>600</timeout>
        </proxy>
    </WS>
    <!-- REST SAMPLES -->
    <process name="MaarchRestWSProcessFromScan">
        <loop xpath="/Batch/Documents/Document">
            <call name="/resources" method="POST">
                <argument type="entity" name="encodedFile" eval="base64_encode(file_get_contents($Element-&gt;path))"/>
                <argument type="entity" name="type_id">108</argument>
                <argument type="entity" name="destination">COU</argument>
                <argument type="entity" name="priority">poiuytre1357nbvc</argument>
                <argument type="entity" name="category_id">incoming</argument>
                <argument type="entity" name="format" attribute="extension"/>
                <argument type="entity" name="status">INIT</argument>
                <return>
                    <resId metadata="resId" />
                </return>
            </call>
        </loop>
    </process>
    <process name="MaarchRestWSProcessFromMail">
        <loop xpath="/Batch/Documents/Document">
            <call name="/resources" method="POST">
                <argument type="entity" name="encodedFile" eval="base64_encode(file_get_contents($Element-&gt;path))"/>
                <argument type="entity" name="format" attribute="extension"/>
                <argument type="entity" name="status">INIT</argument>
                <argument type="entity" name="type_id" metadata="type_id"/>
                <argument type="entity" name="category_id">incoming</argument>
                <argument type="entity" name="subject" metadata="subject"/>
                <argument type="entity" name="doc_date" metadata="doc_date"/>
                <argument type="entity" name="destination" metadata="destination"/>
                <argument type="entity" name="initiator" metadata="destination"/>
                <argument type="entity" name="priority">poiuytre1357nbvc</argument>
                <argument type="entity" name="custom_t10" xvalue="./Metadata/fromaddress"/>
                <argument type="entity" name="custom_t11" xvalue="./Metadata/toaddress"/>
                <argument type="entity" name="custom_t12" xvalue="./Metadata/ccaddress"/>
                <argument type="entity" name="source" xvalue="./Metadata/message_id"/>
                <argument type="entity" name="nature_id">email</argument>
                <argument type="entity" name="exp_contact_id" xvalue="./Metadata/fromaddress"/>
                <argument type="entity" name="address_id" xvalue="./Metadata/fromaddress"/>
                <return>
                    <resId metadata="resId" />
                </return>
            </call>
            <loop xpath="Attachments/Attachment">
                <call name="/res" method="POST">
                    <argument type="entity" eval="base64_encode(file_get_contents($Element-&gt;path))" name="encodedFile"/>
                    <argument type="entity" name="data">
                        <column>title</column>
                        <value metadata="filename"/>
                        <type>string</type>
                    </argument>
                    <argument type="entity" name="data">
                        <column>res_id_master</column>
                        <value xvalue="ancestor::Document/Metadata/resId"/>
                        <type>integer</type>
                    </argument>
                    <argument type="entity" name="data">
                        <column>coll_id</column>
                        <value>letterbox_coll</value>
                        <type>string</type>
                    </argument>
                    <argument type="entity" name="data">
                        <column>attachment_type</column>
                        <value>incoming_mail_attachment</value>
                        <type>string</type>
                    </argument>
                    <argument type="entity" name="collId">letterbox_coll</argument>
                    <argument type="entity" name="table">res_attachments</argument>
                    <argument type="entity" name="format" attribute="extension"/>
                    <argument type="entity" name="status">TRA</argument>
                    <return>
                        <resId metadata="resId" />
                    </return>
                </call>
            </loop>
        </loop>
    </process>
    <!-- SOAP SAMPLES -->
    <process name="MaarchSoapWSProcessFromMail">
            <loop xpath="Attachments/Attachment">
                <call name="storeResource">
                    ...
                </call>
            </loop>
        </loop>
    </process>
</MaarchWSClient>

Déclaration du frontal :

<!-- REST FRONTAL -->
<WS name="MaarchRestWS" type="REST" uri="http://superadmin:superadmin@127.0.0.1/MaarchCourrier/rest/" />
<!-- SOAP FRONTAL -->
<WS name="MaarchSoapWS" type="SOAP" uri="http://127.0.0.1/MaarchCourrier/ws_server.php?WSDL" SSL="false" cacheUse="0" >
    <proxy>
        <user>superadmin</user>
        <pass>superadmin</pass>
        <timeout>600</timeout>
    </proxy>
</WS>

WS name identifiant de la déclaration du frontal webservice utilisé dans le fichier de configuration générale Capture.xml. Ex : pour le protocole REST nous avons dans le jeu de démo la déclaration du WS MaarchRestWS. Pour le protocole SOAP MaarchSoapWS. Dans le cas d’un frontal REST il faut déclarer l’identifiant et le mot de passe d’accès à l’application dans l’uri.
WS type type de webservice. peut prendre REST ou SOAP comme valeur.
WS uri uri du frontal webservice de votre application cible.
WS SSL flag permettant d’indiquer si le frontal de webservice utilise le protocole SSL. Prend true ou false comme valeur. Utile uniquement dans le cas d’un frontal SOAP.
WS proxy dans le cas d’un frontal SOAP uniquement, il faut spécifier ici l’identifiant et le mot de passe d’accès à l’application.

Déclaration des webservices :

<process name="MaarchRestWSProcessFromScan">
    <loop xpath="/Batch/Documents/Document">
        <call name="/res" method="POST">

process name identifiant global des webservices à utiliser pour la communication avec l’application cible (dépendant de l’id WS utilisé). Ex : pour le protocole REST nous avons dans le jeu de démo la déclaration du process MaarchRestWSProcessFromMail. Pour le protocole SOAP MaarchSoapWSProcessFromMail.
loop xpath permet de naviguer dans le fichier xml de traitement du batch. Ceci permet au module MaarchWSClient de traiter par exemple la communication vers l’application cible de tous les documents capturés et/ou de leurs pièces jointes.
call name désigne le webservice à contacter.
call method dans le cas du protocole REST uniquement, précise la méthode HTTP à appliquer. Peut prendre GET, POST, UPDATE ou DELETE comme valeur. Cette liste de valeurs est également dépendante des possibilités du webservice contacté.

Passage des paramètres aux webservices :

<argument type="entity" name="encodedFile" eval="base64_encode(file_get_contents($Element-&gt;path))"/>
<argument type="entity" name="fileFormat" attribute="extension"/>

argument name nom de l’argument.
argument eval expression XML permettant de faire appel à des fonctions de transformation des valeurs des paramètres passés.
argument type uniquement dans le cas d’un webservice de type REST. Définit si le paramètre est passé dans le body ou l’entête HTTP de l’appel au webservice. Peut prendre comme valeur entity (body) ou query (entête). Cette liste de valeurs est également dépendante des possibilités du webservice contacté.
argument attribute permet d’aller récupérer dans le fichier XML de traitement du batch un attribut du document ou de la pièce jointe capturée.

Passage des valeurs des paramètres :

<argument type="entity" name="data">
    <column>doc_date</column>
    <value metadata="doc_date" />
    <type>date</type>
</argument>
<argument type="entity" name="data">
    <column>custom_t10</column>
    <value xvalue="./Metadata/fromaddress" />
    <type>string</type>
</argument>

value metadata permet d’aller récupérer une valeur positionnée par un autre module (ex : MailCapture) dans le fichier XML de traitement du batch du document ou de la pièce jointe capturée.
value xvalue permet d’aller récupérer via une recherche XML une valeur positionnée par un autre module (ex : MailCapture) dans le fichier XML de traitement du batch du document ou de la pièce jointe capturée.
Attention, quelques champs ont des comportements spécifiques :
- 1) Dans le cas où la colonne custom_t10 est renseignée, cela fera le lien entre l'adresse email de l'expéditeur, et l'utilisateur destinataire dans l'application Maarch Courrier. Cela renseignera également l'entité destinatrice. Cela est utile dans le cas où un collaborateur reçoit un courriel dans sa boite personnelle et qu'il le transfère sur la boite qui est capturée. Il faut donc renseigner le champ custom_t10 uniquement avec l'adresse email de l'expéditeur.
- 2) Si le champ exp_contact_id contient une adresse mail, cela fera le lien entre le courrier et un contact existant dans l'application courrier.
- 3) Si le champ address_id contient une adresse mail, cela fera le lien entre le courrier et l'adresse d'un contact existant dans l'application courrier.
- 4) Si le champ alt_identifier est présent et sans valeur, cela ajoutera un numéro chrono au document, en fonction de la séquence des numéros chronos.

Paramétrage du retour du web service :

<return>
    <resId metadata="resId" />
</return>

return définit ce que va renvoyer le webservice contacté. Les valeurs retournées par le webservice seront alors inscrites dans le fichier XML de traitement du batch.

Documentation Maarch Capture