Package: hito-mail
hito_mail: gestion des listes Zimbra et LISTSERVCe module contient des scripts pour créer et mettre à jour les listes Zimbra et LISTSERV associées au laboratoire
et à ses différentes entités (pole, département, service...), à partir des informations contenues dans Hito.Pour tous les scripts indiqués ci-dessous, il y a une option--helpqui permet de connaitre la liste des
options et paramètres du script.InstallationLe déploiement du modulehito_mailnécessite le déploiement d'un environnement Python, de préférence distinct
de ce qui est délivré par l'OS car cela pose de gros problèmes avec les prérequis sur les versions
des dépendances. Les environnements recommandés sontpyenv,poetryouAnaconda.
Pour la création d'un environnement virtuel avec Conda, voir ladocumentation spécifique.Pour installer le modulehito_mail, il faut utiliser les commandes suivantes :pipinstallhito_mailhito2listsCette commande permet de produire les commandes pour créer et mettre à jour des listes Zimbra ou LISTSERV à partir de la base Hito
(base RH). L'information Hito doit être exportée dans un CSV (utf-8) avec au moins les 4 colonnes suivantes : nom,
prénom, email, service. Le service doit être au formatpole - equipe - service(interprété comme 3 niveaux hiérarchiques)
si le paramètre de configurationhito_team_formatestTrueou doit être dans 3 colonnes différentes sihito_team_formatestFalse.hito2listspermet de gérer 2 types de liste :Les listes basées sur l'affectation des personnes dans Hito. Ce sont les listes générées par défaut. En plus de la
création des listes, il est possible de créer un fichier contenant la liste des listes créées, au format HTML, CSV ou
texte suivant l'extension (respectivement.html,.csvor something else).Une ou plusieurs listes avec l'ensemble du personnel présent dans Hito, indépendamment de son affectation. Ce sont
les listes générées lorsque l'option--personnelest spécifiée. Dans ce mode, le nom de la liste à générer peut être spécifié
avec l'option--list-nameou bien être définie dans le fichier de configuration (dans ce cas, on peut générer plusieurs listes).
Il est aussi possible de donner une liste de personne qui doivent être exclues de la liste du personnel, à travers un CSV
spécifique spécifié avec l'option--exclude-list(la seule colonne obligatoire est l'email).L'option--outputest requise sauf si l'option--executeest présente : c'est le fichier produit parhito2listsdans le format spécifié par--format. Le
format par défaut estzimbrapour les listes issues de Hito etlistservpour les listes de l'ensemble du personnel. Il
est aussi possible de générer une liste de participant Limesurvey avec le formatlimesurvey.L'option--executeest supportée avec les formatszimbraetlistserv. Au lien de produire un fichier avec les commandes
à exécuter pour mettre les listes à jour, les commandes sont directement exécutées sur le serveur Zimbra (voir la sectionzimbradu fichier de configuration) ou LISTSERV (voir la sectionlistservdu fichier de configuration).Update et reset modePar défaut,hito2listsgénére les commandes nécessaires pour mettre à jour les listes (listes associées aux équipes ou listes
de tout le personnel). Cela inclut :Ajouter les nouveaux membres dans les listes existantes ou les nouvelles listesRetirer les membres qui ne font plus partie d'une listeSupprimer les listes qui n'existent plus (pour celles associées aux équipes uniquement)Par défaut, le ficher CSV doit se trouver dans un repository Git. Si on utilise l'option--git-commit, la version
précédente du CSV est récupéré dans le commit indiqué (par son ID/hash). En l'absence de cette option, si le fichier CSV
a été modifié depuis le dernier commit, la version précédente est récupérée dans le dernier commit. Si le fichier n'a
pas été modifié, la version précédente est recherchée dans l'historique Git (premier commit antérieur modificant le
fichier CSV). Il est aussi possible d'utiliser l'option--previouspour indiquer le fichier correspondant à une version antérieure du CSV au lieu d'utiliser Git.La mise à jour respecte les informations se trouvant éventuellement dans le fichier spécifié par--additional-lists, soit :Les personnes devant être ajoutées dans les listes bien que les informations Hito ne le spécifient pasLes personnes qui ont demandé à être retirées d'une liste auxquelles elles devraient appartenir d'après les informations
extraites de HitoPour cette raison, les personnes ajoutées via--additional-listssont systématiquement réajoutées dans la mise à jour.Le seul cas qui ne peut pas être géré par le script et demande une action manuelle est celui de personnes ayant demandé
à être retirées d'une liste puis demandant à y être réintégrées (suppression du opt-out du fichier spécifié par--additional-lists).Pour regénérer le contenu des listes, il faut utiliser l'option--reset-lists. Dans ce cas, il
est possible de spécifier une ou des listes à regenérer avec l'option--list-pattern. La valeur
spécifié est interprétée comme une regex appliquée au nom des listes : celles qui ne correspondent
pas sont ignorées. Par exemple,--list-pattern ing-regénerera toutes les listes qui
commencent par-ing-(et ignorera doncingenierie).Remarque: à casue de limitation dans l'interface d'administration Zimbra, l'option--reset-listsne supprime pas les membres actuels de la liste avant d'ajouter les membres
issus de Hito ce qui peut laisser des membres qui devraient être supprimés. Pour faire un
reset complet, il faut utiliserzmprovpour supprimer les membres courants (sans détruire la
liste qui peut être membre d'autres listes) puis exécuterhito2lists --reset-lists. Pour supprimer
les membres d'une liste, utiliser une commande telle que:# Définir la variable listes avec les noms de liste appropriéeslistes='ing-informatique ing-mecanique'forlistein${listes};dol_email=${liste}@ijclab.in2p3.fr;echoRemovingmembersfrom${l_email};zmprovrdlm${l_email}$(zmprovgdl${l_email}|grepzimbraMailForwardingAddress|awk-F": "'{print $2 }');doneAjout/retrait de personnes dans une listeLe fichier spécifié par--additional-listspermet de définir des emails qui doivent être ajoutés ou supprimés des listes
issues de Hito. Il y a un paramètre spécifique pour ajouter/ou enlever une liste issue des groupes définies dans Hito
(--listset--lists-optout) et
pour ajouter/enlever une personne de la liste de l'ensemble du personnel (--personnel-listset--personnel-lists-optout)
afin de détecter plus facilement les erreurs de
configuration mais le fonctionnement est le même dans les deux cas. Les personnes ajoutées n'ont pas besoin d'être déclarées
dans Hito. Les listes spécifiées pour les ajouts doivent exister. Le format du fichier spécifié par--additional-listsest :"email1":
  lists:
    - list1
    - list2
  lists-optout:
    - list3
    - list 4
   personnel-lists-optout:
    - ijclab-forum-l

"email2":
  lists:
    - Anotherlist1
    - list2

"email3":
  personnel-lists:
    - ijclab-personnels-lFichier de configurationLe fichier de configuration par défaut esthito2lists.cfg. Un autre fichier peut être spécifié avec l'option--config.
Ce fichier peut contenir les paramètres suivants :teams:
  aliases:
    fullname: alias
    fullname2: alias2

  reserved_names:
    - reserved1
    - reserved2

  short_names:
    long_team_name1: short_name
    long_team_name2: short_name2

  sublist_disabled:
    - team1
    - team2

# List the list to produce with all the persons in the input CSV
general_lists:
  format: listserv
  lists:
    - ijclab-personnels-l
    - ijclab-forum-l

# Nom des colonnes dans le fichier CSV produit à partir de Hito
csv_columns:
  hito_team_format: True
  names:
    name: "Nom"
    givenname: "Prénom"
    email: "email"
    service: "Équipe"

# Nom de la colonne email dans le fichier spécifié par --exclude-list
exclusion_list:
  columns:
    email: "E_MAIL"

# Paramaters to connect to Zimbra for updating the lists
zimbra:
  server: zimbra.dom.ain
  port: port_number
  user: zimbra_admin_user
  password: zimbra_admin_pwd (empty string if a SSH key is used)
  ssh_key_path: path to the SSK (private) key to use
  command: 'zimbra administration commmand'

listserv:
  smtp_relay: smtp.dom.ain
  # server is the management email for the LISTSERV service
  server: listserv@dom.ain
  # Subject of emails sent to LISTSERV (date/time will be appended) - Optional
  mail_subject: LISTSERV update from Hito
  # Email of the list owner to use to manage the lists (must be registered as a list owner on LISTSERV)
  admin_email: list-mgrs@dom.ain
  # List maangement password if any. Must be the same for all the lists managed by the script.
  admin_password: LISTERV_pwdLes valeurs decsv_columnsindiquées sont les valeurs typiques pour un export depuis Hito. Si le fichier est généré
autrement et contient 3 colonnes, il faut indiquer des valeurs telles que :csv_columns:
  hito_team_format: False
  names:
    name: "NOM_USUEL"
    givenname: "PRENOM"
    email: "E_MAIL"
    pole: "POLE"
    equipe: "DEPARTEMENT"
    service: "SERVICE"(base)Pour les paramètres relatifs au service Zimbra et LISTSERV, voir le fichier d'exemple de configuration fournit
avec le module.hito_exporthito_exportpermet de faire l'export des données de Hito sous la forme d'un fichier CSV compatible
avechito2listsethito2nsippuis de les exécuter pour mettre à jour respectivement les
listes Zimbra et/ou LISTSERV et l'annuaire (NSIP). Cette commande
est conçue pour être mise dans un cron afin de faire une mise à jour régulière des listes construites à partir d'Hito.
Les principales fonctionnalités sont :Récupération des données Hito dans un fichier CSV faisant partie d'un repository Git. Si une version précédente du
fichier CSV existe avec des modifications non enregistrées dans Git, le script refuse de faire un nouvel export.Si le nouveau fichier CSV contient des modifications par rapport à la version précédente (détectées via Git), exécution
dehito2lists --executepour mettre à jour les listes sur le serveur Zimbra et/ou LISTSERV à partir des modifications depuis la
version précédente du fichier CSV puis exécution dehito2nsip --executepour mettre à jour l'annuaireSi la mise à jour se déroule sans erreur, commit de la nouvelle version du fichier CSV et éventuellement push
du commit sur un Git remote.Si la mise à jour produit une erreur, suppression de la nouvelle version du fichier CSVusage:hito_export.py[-h][--configCONFIG][--no-push][--verbose]optionalarguments:-h,--helpshowthishelpmessageandexit--configCONFIGConfigurationfile(D:zimbra-lists\hito_export.cfg)--no-pushGitpushofanewCSVdisabled--verbosePrintdebuggingmesssagesLa principale option est--configqui spécifie le fichier de configuration à utiliser. If--verboseest présent, il est
passé àhito2lists.--no-pushsupprime le Git push après le commit de la nouvelle version du fichier CSV, même s'il
est activé dans le fichier de configuration : cette option ne doit normalement être utilisée que lors des tests pour
simplifier l'effacement des actions qui ont eu lieu pendant les tests.Cette commande est généralement exécutée en cron avec une entrée similaire à :00 19 * * * root ( date --iso-8601=seconds; /path/to/anaconda/envs/hito2zimbra/bin/python /path/to/hito_export.py --verbose --config /path/to/hito_export.cfg) >> /var/log/hito_lists_update.log 2>&1Configuration filehito_exportrequiertun fichier de configuration pour définir l'accès à la database Hito et les paramètres
à utiliser avechito2lists. Par défaut le nom du fichier esthito_export.cfget il doit se trouver soit dans
le répertoire contenant le fichier CSV, soit dans le répertoire où se trouvehito_export.cfg. Voir l'exemple
fourni dans le module pour plus de détails.