Le fonctionnement de Maarch2Maarch¶

Ce document sert à comprendre le modèle Maarch2Maarch, les responsabilités des deux instances, les messages échangés et les causes habituelles d'erreur.

Il ne remplace pas :

la référence des webservices, qui décrit les routes, les corps HTTP et les codes de réponse : Maarch2Maarch ;
le How-to Maarch2Maarch, qui décrit la configuration et la recette pas à pas : Déploiement du MAARCH2MAARCH (M2M)

Objectif¶

Maarch2Maarch permet à une instance Maarch Courrier de transmettre un pli numérique à une autre instance Maarch Courrier. Le pli est construit à partir d'un courrier, de ses documents, de ses notes et de ses métadonnées, puis il est transporté sous forme de paquet SEDA.

L'instance destinataire ne reçoit pas seulement un fichier. Elle reconstruit un contexte métier : un courrier principal, des pièces jointes, des notes, un contact émetteur et un historique d'échange.

Maarch2Maarch ajoute aussi une boucle de suivi. L'instance destinataire renvoie un accusé technique, puis une réponse de traitement. Ces messages permettent à l'instance émettrice de savoir si le paquet est arrivé et s'il a été traité.

Acteurs¶

Acteur	Responsabilité
Instance émettrice	Prépare le pli, génère le SEDA, conserve le message envoyé et déclenche le transport.
Instance destinataire	Reçoit le SEDA, contrôle le paquet, crée les données métier et renvoie les messages de suivi.
Contact M2M	Représente l'autre instance dans Maarch Courrier et porte son identifiant externe M2M.
Entité émettrice	Fournit l'identité organisationnelle inscrite dans le message SEDA.
Utilisateur technique ou fonctionnel	Porte les droits nécessaires à l'envoi ou à la réception du pli.

Objets métier¶

Objet	Rôle dans Maarch2Maarch
Pli numérique	Ensemble transmis entre deux instances.
Paquet SEDA	Représentation technique du pli, de ses fichiers et de ses métadonnées.
MessageExchange	Trace locale d'un message envoyé ou reçu.
Accusé technique	Confirmation que le paquet a été reçu et reconnu techniquement.
Réponse de traitement	Confirmation que l'instance destinataire a traité le contenu du pli.
Notification de suivi	Message complémentaire rattaché à un échange existant.

Cycle d'un pli classique¶

Un pli classique commence sur une instance émettrice à partir d'un courrier principal. L'utilisateur choisit une entité émettrice, un ou plusieurs contacts M2M destinataires, un document principal et éventuellement des pièces jointes ou des notes.

L'instance émettrice transforme cette sélection en objet d'échange. Cet objet contient l'organisation émettrice, l'organisation destinataire, les documents, les empreintes, les métadonnées et les commentaires. Il est ensuite sérialisé en paquet SEDA et sauvegardé localement comme MessageExchange.

Le paquet est transporté vers l'instance destinataire. Le canal habituel est le webservice, car il permet de recevoir automatiquement les accusés et les réponses. Un canal e-mail existe aussi, mais il n'offre pas le même niveau de suivi automatique.

À la réception, l'instance destinataire extrait le paquet, contrôle son type, crée ou retrouve le contact émetteur, puis crée le courrier principal. Les commentaires du message deviennent des notes. Les fichiers secondaires deviennent des pièces jointes avec le type configuré pour la réception Maarch2Maarch.

Après ce traitement, l'instance destinataire renvoie deux messages de suivi : un accusé technique, puis une réponse de traitement. L'instance émettrice les rattache au MessageExchange initial.

Instance A
    | pli SEDA
    v
Instance B
    | accusé + réponse de traitement
    v
Instance A

Ce que conserve MessageExchange¶

MessageExchange est le journal technique et fonctionnel de l'échange. Il permet de suivre ce qui a été émis, reçu, acquitté, traité ou signalé en erreur.

Un enregistrement MessageExchange contient notamment l'identifiant du message, son type SEDA, son statut d'envoi, les dates de création, de réception ou d'opération, le courrier principal rattaché, le destinataire, les informations d'expéditeur et le fichier archivé stocké dans le docserver.

Cette trace est essentielle pour trois raisons :

elle permet d'afficher le suivi dans le courrier concerné ;
elle permet de rattacher les accusés et réponses au message d'origine ;
elle sert à déterminer si un retour de documents est encore possible.

Rôle de la configuration¶

La configuration Maarch2Maarch ne décrit pas seulement un canal de communication. Elle définit aussi comment un pli reçu devient un courrier local.

Elle détermine le type de courrier créé, son statut, sa priorité, son modèle d'indexation, la bannette de redirection après import et le type appliqué aux pièces jointes importées.

La communication configurée indique comment l'instance se présente aux autres instances. Elle est inscrite dans les messages SEDA pour permettre à l'autre instance de répondre au bon endroit.

Le type de pièce jointe utilisé à la réception doit être un type exploitable comme pièce jointe métier. Un type réservé à un autre usage, par exemple une réponse signée, ne convient pas pour importer les pièces jointes d'un pli M2M.

Rôle des contacts M2M¶

Un contact M2M est la représentation locale d'une instance distante. Son identifiant externe M2M doit correspondre à l'identifiant organisationnel porté par les messages SEDA.

Cet identifiant est important parce qu'il sert à reconnaître l'autre instance, à créer ou retrouver le contact émetteur à la réception, et à vérifier l'éligibilité des retours.

Si l'identifiant externe ou la communication du contact ne correspond pas à ce qui est annoncé dans les messages, Maarch Courrier peut recevoir le paquet mais ne plus pouvoir interpréter correctement le lien fonctionnel avec l'organisation distante.

Demande de retour¶

Une demande de retour est un pli classique dans lequel l'instance émettrice indique qu'elle attend des documents en retour. Cette intention est portée dans les options Maarch du paquet SEDA.

Avant l'envoi, l'instance émettrice vérifie que le destinataire sait gérer ce mécanisme. Cette vérification évite d'envoyer une demande de retour à une instance qui ne saurait pas la comprendre ou la restituer dans l'interface.

À la réception, la demande est mémorisée comme un échange en attente de retour. Le courrier créé chez le destinataire porte donc l'information qu'un retour peut être préparé plus tard.

Envoi d'un retour¶

Le retour est l'échange inverse. L'instance qui avait reçu la demande sélectionne les documents à renvoyer, puis émet un nouveau paquet SEDA vers l'instance qui avait initié la demande.

Le retour ne crée pas un nouveau courrier principal sur l'instance d'origine. Il rattache les documents retournés au courrier initial, grâce à l'identifiant du courrier conservé dans les options Maarch du message.

Un retour n'est possible qu'une seule fois pour une même organisation et un même cycle d'échange. Cette restriction évite d'avoir plusieurs retours concurrents pour la même demande.

Modes Maarch2Maarch¶

Les modes Maarch2Maarch décrivent l'état fonctionnel d'un échange de retour. Ils ne remplacent pas les types SEDA ; ils ajoutent une information métier propre à Maarch Courrier.

Mode	Sens fonctionnel
`request_return`	Le pli demande un retour.
`waiting_return`	Le destinataire a reçu une demande et peut préparer un retour.
`prepare_return`	Le destinataire envoie les documents retournés.
`returned`	L'instance d'origine a reçu le retour.

Lorsqu'un paquet est reçu, le mode peut être transformé pour représenter l'état local. Une demande émise devient une attente de retour chez le destinataire. Un retour préparé devient un retour reçu chez l'instance d'origine.

Suivi et messages SEDA¶

Maarch2Maarch s'appuie sur plusieurs types SEDA. Le pli principal est un ArchiveTransfer. L'accusé technique est un Acknowledgement. La réponse de traitement est un ArchiveTransferReply. Les notifications de suivi sont des ArchiveModificationNotification.

Ces types servent à rattacher chaque message à l'échange initial. Les identifiants SEDA permettent de retrouver le MessageExchange concerné et de mettre à jour les dates, le statut ou le suivi affiché à l'utilisateur.

La différence entre accusé et réponse est importante. L'accusé confirme que le paquet a été reçu techniquement. La réponse confirme que le contenu a été traité par l'instance destinataire.

Transport¶

Le canal webservice transporte le paquet SEDA encodé vers l'instance distante. Avant l'envoi, Maarch Courrier relit le fichier archivé stocké dans le docserver et vérifie son empreinte. Cette vérification garantit que le fichier transmis est bien celui qui a été sauvegardé.

Si le transport réussit, le message local passe en statut envoyé. Si le transport échoue, il passe en erreur et l'erreur distante peut être remontée à l'utilisateur.

Le canal e-mail crée un message à envoyer avec le paquet associé. Le paquet SEDA est alors transporté comme pièce jointe de l'e-mail. Côté destinataire, Maarch Courrier ne lit pas automatiquement la boîte mail pour importer ce paquet. Un utilisateur doit récupérer le ZIP reçu et l'importer depuis l'écran Enregistrer un pli numérique.

Une fois le ZIP importé dans Maarch Courrier, le traitement redevient le même que pour un transport webservice : le paquet est extrait, contrôlé, puis converti en courrier, notes, pièces jointes et messages de suivi.

Le canal e-mail reste utile pour certains usages, mais il n'offre pas le même chaînage automatique des accusés, réponses et notifications que le canal webservice.

Lecture des erreurs¶

Une erreur affichée sur l'instance émettrice peut avoir été produite par l'instance destinataire. C'est particulièrement vrai pour les erreurs de transport webservice : Maarch Courrier remonte alors la réponse de l'autre instance dans une erreur curl.

Pour comprendre l'origine d'une erreur, il faut donc raisonner sur les deux côtés de l'échange : ce que l'instance émettrice a construit et envoyé, puis ce que l'instance destinataire a contrôlé, importé ou refusé.

Les causes fréquentes sont une communication de contact incorrecte, une instance distante inaccessible, un problème SSL, une limite de taille HTTP, une configuration Maarch2Maarch incomplète, un type de pièce jointe non éligible ou un paquet SEDA incohérent avec le message attendu.

Contraintes d'intégration¶

Maarch2Maarch dépend de la cohérence entre les deux instances. Les identifiants M2M, les communications annoncées, les droits, les types de documents et les types de pièces jointes doivent être alignés avec le scénario d'échange.

Les URL doivent être stables et accessibles de serveur à serveur. Les tailles de paquets doivent rester compatibles avec le reverse proxy, PHP et le serveur web. Les horloges des serveurs doivent être cohérentes pour faciliter la lecture des dates et de l'ordre des évènements.

Quand un problème apparaît, l'instance qui affiche l'erreur n'est pas toujours celle qui l'a produite. L'analyse doit donc prendre en compte l'historique et les journaux des deux instances.