Connecteur Maarch

Fonctionnalités

Le connecteur est capable de récupérer les courriers dans un certain statut, permettant de lui associer des demandes. Le courrier peut aussi être refusé s'il est jugé qu'il n'est finalement pas du ressort de la GRC. En fin de traitement de la demande il sera possible de lui apporter une réponse, pour l'instant une simple réponse sous forme de texte injecté dans l'historique du courrier.

Scénario détaillé

Cf. recette complète sur Ville d'Avray : https://dev.entrouvert.org/projects/ville-d-avray/wiki/Sc%C3%A9nario_de_recette_du_connecteur_Maarch%3EPublik

Limitations

1. On ne peut pas répondre à un courrier par un document
2. Coté Publik nous pouvons associer plusieurs démarches à un courrier ce qui dans Maarch ne sera pas possible puisque les champs external_id et external_link n'accepte qu'une unique valeur,
3. La création d'une demande pour un courrier fait passer le statut du courrier dans Maarch dans le statut "GRC_TRT" (voir plus bas), de même on ne peut faire ça qu'une seule fois pour que cela ait un sens,
4. De la même manière le fait de produire plusieurs réponses à un courrier dans Maarch obligera à passer plusieurs fois dans le statut "Réponse émise par la GRC" rendant l'historique peu cohérent.

Pour le deuxième point le ticket #30046 évoque un contournement possible.

Configuration de Maarch

Les ressources (ou courrier, le modèle de donnée n'est pas bien clair) de Maarch doivent posséder les attributs suivants:

Un utilisateur est créé sur Maarch ayant accès aux web-services REST, il servira à welco pour moissonner l'instance de Maarch.

Ensuite il faudra disposer des statuts suivants (qu'on pourra nommer comme on veut, je donne juste les valeurs par défaut du connecteur qui sont configurable):

Configuration du connecteur (de la brique welco)

La configuration se fait via la clé de configuration Django MAARCH_FEEED, comme cela (à configurer par exemple via hobo en créant une variable SETTING_MAARCH_FEED dans le service courrier)

MAARCH_FEED = {
   'ENABLE': True  # optionnel, permet de désactiver le raccordement, par défaut à True
   'URL': 'https://maarch-api-endoint' # Maarch API endpoint 
   'USERNAME': 'xxx'  # obligatoire, username de l'utilisateur dans Maarch
   'PASSWORD': 'yyy':  # obligatoire, mot de passe de l'utilisateur dans Maarc
   'STATUS_GRC': 'GRC'  # optionnel, voir plus haut, valeur par défaut identique
   'STATUS_RECEIVED': 'GRC_TRT'  # optionnel, voir plus haut, valeur par défaut identique
   'STATUS_SEND': 'GRC_SENT'  # optionnel, voir plus haut, valeur par défaut identique
   'STATUS_REFUSED': 'GRC_REFUSED'  # optionnel, voir plus haut, valeur par défaut identique
   'STATUS_RESPONSE': 'GRC_RESPONSE'  # optionnel, voir plus haut, valeur par défaut identique
}

Utilisation dans un workflow w.c.s.

On retrouvera dans le contexte de soumission de la demande le numéro du courrier dans Maarc via la variable form_submission_context_external_id sour la forme 'maarch-%(res_id)s'.

Envoyer une réponse depuis w.c.s.

Pour cela on utilisera une API exposée par la brique courrier, en supposant que la brique courrier se nomme courrier, on pourra créer un appel de web service dans une action de traitement dans w.c.s. avec les paramètres suivants :

Description du code dans welco

Le numéro du courrier dans Maarch (le res_id) est conservé sous la forme formatée 'maarch-%(res_id)s' dans le champ external_id (à ne pas confondre avec l'external_id dans Maarch) du modèle Mail (dans weco/sources/mail/models.py). C'est la seule donnée venant de Maarch qui soit conservée dans welco.

Fichier Description
welco/sources/mail/maarch.py l'objet de base pour interagir avec Maarch, implémente les appels de WS à Maarch
welco/sources/mail/utils.py un adapteur pour intégrer Maarch aux besoin de Welco, récupérer la configuration depuis les settings Django
welco/sources/mail/management/commands/feed_mail_maarch.py commande lancé par cron pour moisonner régulièrement Maarch
welco/sources/mail/__init__.py réaction au signal créant une association entre un courrier et une demande dans w.c.s. pour le signaler à Maarch
welco/sources/mail/views.py modifie le comportement en cas de rejet d'un courrier venant de Maarch (notification de Maarch), implémentation du WS à destination de w.c.s. pour émettre une réponse à un courrier Maarch

Description des WS Maarch utilisés

Nous utilisons les web-service suivants:

Documentation : https://docs.maarch.org/gitbook/html/MaarchCourrier/18.10/guat/guat_architecture/API_REST/home.html

Quelques requêtes :

# Courriers en statut GRC
curl -u 'login:passwd' -d "select=*&clause=status='GRC'&orderBy[]=res_id" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://maarch-api/rest/res/list

# Courriers en statut  GRC*
curl -u 'login:passwd' -d "select=*&clause=status like 'GRC%'&orderBy[]=res_id" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://maarch-api/rest/res/list

# Tous les courriers
curl -u 'login:passwd' -d "select=*&clause=1=1&orderBy[]=res_id" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://maarch-api/rest/res/list

Admin système

Récupération des courriers :

sudo -u welco welco-manage tenant_command feed_mail_maarch --domain nom_du_tenant -v2