Aller au contenu

Déploiement de Maarch2Maarch (M2M)

Cette procédure explique comment déployer Maarch2Maarch pour échanger des plis numériques entre deux instances Maarch Courrier.

Pour comprendre le modèle fonctionnel, consultez Le fonctionnement de Maarch2Maarch. Pour les contrats HTTP, consultez la référence des webservices Maarch2Maarch.

Pré-requis

  • Disposer de deux instances Maarch Courrier installées et accessibles.
  • Avoir accès au répertoire custom/{customId}/config/ de chaque instance.
  • Disposer d'un compte administrateur pour configurer les paramètres, les entités, les contacts et les groupes.
  • Donner le privilège Enregistrer un pli numérique (manage_numeric_package) aux utilisateurs ou comptes techniques qui envoient, reçoivent ou importent des plis numériques.
  • Prévoir un canal de transport : URL webservice, e-mail, ou échange manuel du fichier ZIP.
  • Si le canal e-mail doit être automatisé, disposer d'un composant de capture externe compatible. Maarch Courrier ne lit pas automatiquement une boîte mail pour importer les plis reçus.

Préparer le fichier de configuration

Le fichier de configuration Maarch2Maarch est m2m_config.xml.

  1. Vérifiez que le fichier existe dans le custom de l'instance :
custom/{customId}/config/m2m_config.xml
  1. S'il n'existe pas, copiez le fichier modèle fourni par Maarch Courrier :
config/m2m_config.xml.default

  1. Vérifiez que le fichier est accessible en lecture et en écriture par l'utilisateur système qui exécute l'application.

  2. Renseignez ensuite la configuration depuis l'écran d'administration des paramètres.

Note

À l'ouverture de la configuration Maarch2Maarch, Maarch Courrier peut initialiser le fichier du custom depuis le modèle par défaut. En exploitation, il reste préférable de vérifier explicitement sa présence et ses droits.

Vérifier le docserver des plis numériques

Les plis numériques générés sont stockés dans le docserver ARCHIVETRANSFER, rattaché à la collection archive_transfer_coll.

  1. Vérifiez la présence du type de docserver :
SELECT docserver_type_id, fingerprint_mode
FROM docserver_types
WHERE docserver_type_id = 'ARCHIVETRANSFER';
  1. Vérifiez la présence du docserver :
SELECT docserver_id, docserver_type_id, path_template, coll_id
FROM docservers
WHERE docserver_id = 'ARCHIVETRANSFER';
  1. Si ces lignes sont absentes sur une instance existante, créez-les avec des requêtes compatibles avec le schéma actuel :
INSERT INTO docserver_types (docserver_type_id, docserver_type_label, enabled, fingerprint_mode)
SELECT 'ARCHIVETRANSFER', 'Archives numériques', 'Y', 'SHA256'
WHERE NOT EXISTS (
    SELECT 1 FROM docserver_types WHERE docserver_type_id = 'ARCHIVETRANSFER'
);

INSERT INTO docservers (
    docserver_id,
    docserver_type_id,
    device_label,
    is_readonly,
    is_encrypted,
    size_limit_number,
    actual_size_number,
    path_template,
    creation_date,
    coll_id
)
SELECT
    'ARCHIVETRANSFER',
    'ARCHIVETRANSFER',
    'Dépôt des archives numériques',
    'N',
    false,
    50000000000,
    1,
    '/opt/maarch/docservers/archive_transfer/',
    now(),
    'archive_transfer_coll'
WHERE NOT EXISTS (
    SELECT 1 FROM docservers WHERE docserver_id = 'ARCHIVETRANSFER'
);
  1. Vérifiez que le répertoire du docserver existe sur le serveur et que l'application peut y écrire :
/opt/maarch/docservers/archive_transfer/

Adaptez path_template si le stockage de votre instance utilise un autre emplacement.

Exemple de paquet SEDA transféré

Un pli numérique est une archive ZIP qui contient un bordereau SEDA2 et les fichiers transmis.

Exemple de paquet transféré :

ArchiveTransfer_20181008_164539_bblier.zip
├── ArchiveTransfer_20181008_164539_bblier.xml
└── 0030_1200000707.pdf

Exemple de bordereau SEDA2 généré. Par souci de lisibilité, le contenu encodé en base64 du document est remplacé par BASE64_DU_DOCUMENT.

<?xml version="1.0" encoding="UTF-8"?>
<ArchiveTransfer xmlns="fr:gouv:culture:archivesdefrance:seda:v2.0">
    <Comment>Bernard BLIER (Ville de Maarch-les-bains - Service Courrier - support@maarch.org) :  Votre message est prêt à  être envoyé avec les fichiers joints suivants :&#13;
 &#13;
sdfsddf: sdfsddf.pdf&#13;
    </Comment>
    <Date>2018-10-08T16:45:39+02:00</Date>
    <MessageIdentifier>ArchiveTransfer_20181008_164539_bblier</MessageIdentifier>
    <CodeListVersions>
        <ReplyCodeListVersion>""</ReplyCodeListVersion>
        <MessageDigestAlgorithmCodeListVersion>""</MessageDigestAlgorithmCodeListVersion>
        <MimeTypeCodeListVersion>""</MimeTypeCodeListVersion>
        <EncodingCodeListVersion>""</EncodingCodeListVersion>
        <FileFormatCodeListVersion>""</FileFormatCodeListVersion>
        <CompressionAlgorithmCodeListVersion>""</CompressionAlgorithmCodeListVersion>
        <DataObjectVersionCodeListVersion>""</DataObjectVersionCodeListVersion>
        <StorageRuleCodeListVersion>""</StorageRuleCodeListVersion>
        <AppraisalRuleCodeListVersion>""</AppraisalRuleCodeListVersion>
        <AccessRuleCodeListVersion>""</AccessRuleCodeListVersion>
        <DisseminationRuleCodeListVersion>""</DisseminationRuleCodeListVersion>
        <ReuseRuleCodeListVersion>""</ReuseRuleCodeListVersion>
        <ClassificationRuleCodeListVersion>""</ClassificationRuleCodeListVersion>
        <AuthorizationReasonCodeListVersion>""</AuthorizationReasonCodeListVersion>
        <RelationshipCodeListVersion>""</RelationshipCodeListVersion>
    </CodeListVersions>
    <DataObjectPackage>
        <BinaryDataObject id="res_letterbox_0_104">
            <Attachment filename="0030_1200000707.pdf">BASE64_DU_DOCUMENT</Attachment>
            <MessageDigest algorithm="sha256">d4ae804a0e20cd61d63a92056506fe40fe6d46ade73a5803c54cf5ebf024cc2896133f7314da49edcaab61f9c3049f74030d153b30566f9822f2722173105e95</MessageDigest>
            <Size>111108</Size>
            <FormatIdentification>
                <MimeType>application/pdf</MimeType>
            </FormatIdentification>
        </BinaryDataObject>
        <DescriptiveMetadata>
            <ArchiveUnit id="mail_1">
                <Content>
                    <DescriptionLevel>File</DescriptionLevel>
                    <Title>[CAPTUREM2M]Réponse à votre courrier du 27-06-2018</Title>
                    <OriginatingSystemId>104</OriginatingSystemId>
                    <Status>Nouveau courrier ou document non qualifié</Status>
                    <Writer>
                        <FirstName>Barbara</FirstName>
                        <BirthName>BAIN</BirthName>
                    </Writer>
                    <CreatedDate>2018-06-27</CreatedDate>
                </Content>
                <ArchiveUnit id="archiveUnit_res_letterbox_0_104">
                    <Content>
                        <DescriptionLevel>Item</DescriptionLevel>
                        <Title>sdfsddf</Title>
                        <OriginatingSystemId>104</OriginatingSystemId>
                        <Status>Nouveau courrier ou document non qualifié</Status>
                        <Writer>
                            <FirstName>Barbara</FirstName>
                            <BirthName>BAIN</BirthName>
                        </Writer>
                        <CreatedDate>2018-06-27</CreatedDate>
                    </Content>
                    <DataObjectReference>
                        <DataObjectReferenceId>res_letterbox_0_104</DataObjectReferenceId>
                    </DataObjectReference>
                </ArchiveUnit>
            </ArchiveUnit>
        </DescriptiveMetadata>
        <ManagementMetadata></ManagementMetadata>
    </DataObjectPackage>
    <ArchivalAgency>
        <Identifier>org_987654321_DGS_SF</Identifier>
        <OrganizationDescriptiveMetadata>
            <Name>Préfecture de Maarch Les Bains</Name>
            <Communication>
                <Channel>url</Channel>
                <CompleteNumber>https://cchaplin:maarch@demo.maarchcourrier.com/rest/saveNumericPackage</CompleteNumber>
            </Communication>
            <Contact>
                <PersonName>MARTIN Nicolas</PersonName>
                <Communication>
                    <Channel>phone</Channel>
                    <CompleteNumber></CompleteNumber>
                </Communication>
                <Communication>
                    <Channel>email</Channel>
                    <CompleteNumber>info@maarch.org</CompleteNumber>
                </Communication>
                <Address>
                    <CityName>MAARCH LES BAINS</CityName>
                    <Country>FRANCE</Country>
                    <PostOfficeBox>13</PostOfficeBox>
                    <StreetName>RUE LA PREFECTURE</StreetName>
                </Address>
            </Contact>
        </OrganizationDescriptiveMetadata>
    </ArchivalAgency>
    <TransferringAgency>
        <Identifier>org_987654321_DGS_SF</Identifier>
        <OrganizationDescriptiveMetadata>
            <LegalClassification>Ville de Maarch-les-bains</LegalClassification>
            <Name>Service Courrier</Name>
            <Communication>
                <Channel>url</Channel>
                <CompleteNumber>https://cchaplin:maarch@localhost/maarch_v2</CompleteNumber>
            </Communication>
            <Contact>
                <DepartmentName>Service Courrier</DepartmentName>
                <PersonName>Bernard BLIER</PersonName>
                <Communication>
                    <Channel>phone</Channel>
                </Communication>
                <Communication>
                    <Channel>email</Channel>
                    <CompleteNumber>florian.azizian@maarch.org</CompleteNumber>
                </Communication>
                <Address></Address>
            </Contact>
        </OrganizationDescriptiveMetadata>
    </TransferringAgency>
</ArchiveTransfer>

Configurer la réception sur l'instance locale

Sur chaque instance susceptible de recevoir des plis numériques, cette configuration définit la façon dont un pli reçu devient un courrier local.

  1. Ouvrez l'écran d'administration des paramètres Maarch2Maarch.
  2. Renseignez le type de courrier créé à la réception.
  3. Renseignez le statut initial du courrier reçu.
  4. Renseignez la priorité et le modèle d'indexation appliqués au courrier reçu.
  5. Renseignez la bannette de redirection après import.
  6. Renseignez le type de pièce jointe utilisé pour les fichiers secondaires du pli.
  7. Renseignez les moyens de communication de l'instance locale : URL, e-mail, login et mot de passe selon le canal retenu.
  8. Enregistrez la configuration.

Le type de pièce jointe configuré pour la réception doit être un type de pièce jointe métier. N'utilisez pas un type réservé à un autre usage, par exemple signed_response.

Configurer l'identité M2M des entités

Chaque entité qui reçoit des plis doit porter un identifiant externe M2M stable. Cet identifiant correspond au numéro SIRET de l'organisation, éventuellement complété par l'identifiant de l'entité destinataire lorsqu'une même organisation expose plusieurs services.

  1. Ouvrez l'administration des entités.
  2. Renseignez l'identifiant externe M2M de l'entité destinataire.
  3. Utilisez une valeur unique et partagée avec l'instance émettrice, par exemple 45239273100025/DSI.
  4. Répétez l'opération pour chaque service destinataire.

Dans Maarch Courrier, la génération depuis l'annuaire M2M construit cette valeur avec la forme SIRET/ENTITY_ID. Exemple : 45239273100025/DSI.

L'identifiant externe M2M du contact configuré sur l'instance émettrice doit correspondre à cet identifiant. Dans les anciennes documentations, ce champ est parfois décrit comme le numéro SIRET du destinataire ; en pratique, il doit reprendre exactement l'identifiant M2M de l'entité distante.

Configurer les contacts M2M sur l'instance émettrice

Un contact M2M représente l'instance ou le service destinataire. Seuls les contacts disposant d'un moyen de communication M2M, URL ou e-mail, apparaissent dans l'autocomplétion de l'écran d'envoi.

  1. Ouvrez l'administration des contacts.
  2. Créez ou modifiez le contact de l'organisation destinataire.
  3. Renseignez l'identifiant externe M2M du contact avec l'identifiant de l'entité distante, par exemple le SIRET ou SIRET/ENTITY_ID.
  4. Renseignez le moyen de communication M2M : URL ou e-mail.
  5. Pour le canal URL, renseignez l'URL de l'instance distante et les identifiants du compte technique distant.
  6. Pour le canal e-mail, renseignez l'adresse qui recevra le pli numérique.
  7. Enregistrez le contact.

Warning

Si un contact possède une adresse e-mail M2M, Maarch Courrier utilise le canal e-mail avant le canal URL. Pour forcer un envoi par webservice, utilisez un contact sans e-mail M2M ou un contact séparé dédié au canal URL.

Pour plusieurs services destinataires sur la même instance distante, créez un contact par service avec un identifiant M2M distinct.

Exemple :

Service destinataire Identifiant M2M
Direction des systèmes d'information 45239273100025/DSI
Direction des finances 45239273100025/FIN

Entité destinataire service finances

Entité destinataire service informatique

Contact M2M service informatique

Contact M2M service comptabilité

Choisir le canal d'envoi

Envoi par webservice

Utilisez ce canal lorsque les deux instances peuvent communiquer de serveur à serveur.

  1. Configurez le contact destinataire avec une URL M2M.
  2. Vérifiez que le compte technique distant dispose du privilège manage_numeric_package.
  3. Vérifiez que l'URL distante est accessible depuis le serveur émetteur.
  4. Vérifiez la configuration SSL utilisée pour les appels sortants si un certificat spécifique est requis.

Ce canal permet le suivi le plus complet : accusé technique, réponse de traitement et notifications de suivi.

Envoi par e-mail

Utilisez ce canal lorsque l'instance destinataire ne peut pas être appelée directement par URL.

  1. Configurez l'envoi d'e-mails de l'instance émettrice. Consultez Configurer l'envoi de mails.
  2. Configurez le contact destinataire avec une adresse e-mail M2M.
  3. Envoyez le pli numérique depuis Maarch Courrier.
  4. Côté destinataire, récupérez le ZIP reçu en pièce jointe.
  5. Importez le ZIP depuis le menu Enregistrer un pli numérique.

La transmission par e-mail n'est pas instantanée : elle dépend de la fréquence d'envoi des e-mails et, si une capture externe est déployée, de la fréquence de récupération de la boîte mail.

Import d'un pli numérique

L'automatisation de la réception e-mail nécessite un composant de capture externe capable de lire la boîte mail, récupérer le ZIP et l'importer dans Maarch Courrier. Sans ce composant, l'import est manuel.

Envoi manuel

Utilisez ce canal lorsque le webservice et l'e-mail automatisé ne sont pas disponibles.

  1. Envoyez le pli depuis Maarch Courrier.
  2. Téléchargez le pli numérique depuis la liste des plis envoyés.
  3. Transmettez le ZIP complet au destinataire par un moyen maîtrisé.
  4. Le destinataire importe le ZIP depuis le menu Enregistrer un pli numérique.

Envoyer un pli numérique

  1. Ouvrez un courrier.
  2. Dans la fiche détaillée ou la page de traitement, ouvrez la zone des éléments envoyés.
  3. Cliquez sur l'action Envoyer un pli numérique.
  4. Sélectionnez l'entité émettrice.
  5. Sélectionnez le contact destinataire M2M.
  6. Sélectionnez le document principal et les pièces jointes ou notes à intégrer au pli.
  7. Saisissez l'objet et le contenu du message.
  8. Envoyez le pli.

Création d'un pli numérique

Le premier document sélectionné est utilisé comme document principal du pli. Les autres documents sont transmis comme pièces jointes.

Envoyer une demande de retour

Une demande de retour permet à l'instance destinataire de préparer plus tard un retour de documents vers l'instance émettrice.

  1. Utilisez le canal URL pour le contact destinataire.
  2. Vérifiez que l'instance distante expose la capacité de gestion des retours.
  3. Lors de l'envoi du pli, activez l'option de retour attendu.
  4. Envoyez le pli.

Si l'instance distante ne prend pas en charge les retours, l'envoi est refusé avant transmission du pli.

Importer un pli reçu

L'import manuel est utilisé pour les plis reçus par e-mail sans capture automatique ou transmis hors webservice.

  1. Connectez-vous avec un utilisateur disposant du privilège Enregistrer un pli numérique (manage_numeric_package).
  2. Ouvrez le menu Enregistrer un pli numérique.
  3. Sélectionnez le fichier ZIP reçu.
  4. Lancez l'import.
  5. Vérifiez que le courrier créé s'ouvre ou que la redirection vers la bannette configurée fonctionne.

Import d'un pli numérique

Après import, Maarch Courrier extrait le paquet SEDA, contrôle sa cohérence, crée le courrier, rattache les notes et les pièces jointes, puis enregistre les traces de l'échange. Si l'expéditeur déclaré dans le pli n'existe pas encore comme contact local, Maarch Courrier le crée automatiquement.

Vérifier le suivi

Après l'envoi, le pli apparaît dans la liste des plis numériques envoyés.

Liste des plis numériques

Vérifiez les colonnes suivantes :

Colonne Résultat attendu
De Expéditeur du pli.
À Destinataire du pli.
Reçu le Date renseignée lorsque le destinataire a reçu ou importé le pli.
Pris en charge Date renseignée après la première action de traitement côté destinataire.
Statut Non envoyé uniquement si l'envoi a échoué.

Ouvrez ensuite le détail du pli pour contrôler les éléments envoyés et l'historique. Les actions de workflow réalisées sur le courrier distant ne remontent dans le suivi que si l'action concernée est configurée pour être tracée.

Suivi d'un pli numérique

Charger un jeu de contacts d'exemple

Le dépôt applicatif contient un fichier SQL d'exemple pour préparer des contacts M2M dans un contexte multi-instances :

sql/m2m_contacts_samples.sql

Ce fichier est un exemple de recette. Adaptez les identifiants M2M, les URL, les utilisateurs et les mots de passe avant toute utilisation sur une instance réelle.

Dépannage

Problème Cause probable Solution
Le menu Enregistrer un pli numérique n'est pas visible Le privilège Enregistrer un pli numérique (manage_numeric_package) n'est pas attribué Ajouter le privilège au groupe de l'utilisateur
Le contact destinataire n'apparaît pas dans l'autocomplétion Aucun moyen de communication M2M n'est renseigné sur le contact Renseigner une URL ou une adresse e-mail M2M sur le contact
L'envoi par URL échoue avec une erreur curl URL, authentification, SSL ou instance distante incorrects Tester l'accès serveur à serveur et vérifier le contact M2M
Le destinataire reçoit un e-mail mais aucun courrier n'est créé Aucun composant de capture n'importe automatiquement la pièce jointe Importer le ZIP manuellement ou déployer la capture externe
Le pli est reçu mais les pièces jointes ne sont pas créées Type de pièce jointe de réception inadapté Configurer un type de pièce jointe métier, pas un type réservé
Le destinataire n'est pas reconnu Identifiant M2M du contact différent de l'identifiant de l'entité distante Aligner les identifiants M2M des deux instances
La demande de retour est refusée L'instance distante ne déclare pas la capacité de gestion des retours ou le canal n'est pas URL Vérifier la capacité distante et utiliser le canal URL