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 le protocole 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.
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.
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/" />
    <!-- REST SAMPLES -->
    <process name="MaarchRestWSProcessFromScan">
        <loop xpath="/Batch/Documents/Document">
            <call name="/resources" method="POST">
                <argument type="entity" name="modelId">1</argument>
                <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="doctype">108</argument>
                <argument type="entity" name="chrono">true</argument>
                <argument type="entity" name="destination">15</argument>
                <argument type="entity" name="priority">2</argument>
                <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="modelId">1</argument>
                <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="chrono">true</argument>
                <argument type="entity" name="doctype" metadata="type_id"/>
                <argument type="entity" name="subject" metadata="subject"/>
                <argument type="entity" name="documentDate" metadata="doc_date"/>
                <argument type="entity" name="destination" metadata="destination"/>
                <argument type="entity" name="initiator" metadata="destination"/>
                <argument type="entity" name="priority">2</argument>
                <return>
                    <resId metadata="resId" />
                </return>
            </call>
            <loop xpath="Attachments/Attachment">
                <call name="/attachments" method="POST">
                    <argument type="entity" name="resIdMaster" xvalue="ancestor::Document/Metadata/resId"/>
                    <argument type="entity" name="type">incoming_mail_attachment</argument>
                    <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="title" metadata="filename"/>                    
                    <return>
                        <id metadata="resId" />
                    </return>
                </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/" />

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. 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 comme valeur.
WS uri uri du frontal webservice de votre application cible.

Déclaration des webservices :

<process name="MaarchRestWSProcessFromScan">
    <loop xpath="/Batch/Documents/Document">
        <call name="/resources" 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.
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="format" 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="documentdate" metadata="doc_date"/>
<argument type="entity" name="resIdMaster" xvalue="ancestor::Document/Metadata/resId"/>

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.

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.

Paramétrage des valeurs pour les champs personnalisés :

Certaines données peuvent être renseignées dans les champs personnalisés. Pour cela, il faut au préalable avoir créé/vérifié le champ personnalisé depuis l'administration des "champs personnalisés" puis récupéré l'identifiant du champ personnalisé.

Pour la reprise des paramètres spécifiques aux champs "custom", dans la configuration du fichier. Renseignez les champs avec ce formalisme:

<argument type="entity" name="customFields" eval="[&quot;ID&quot; => &quot;VALEUR&quot;]"/>

exemple :

<argument type="entity" name="customFields" eval="[&quot;3&quot; => &quot;Courriel&quot;]"/>

Documentation Maarch Capture