Documentation

This document in english.

L’utilisation de ce logiciel vous soumet à nos Conditions d’utilisation et à notre Politique de protection des données.

version 1.2.2

Introduction:

eMailerOOo fait partie d’une Suite d’extensions LibreOffice et/ou OpenOffice permettant de vous offrir des services inovants dans ces suites bureautique.

Cette extension vous permet d’envoyer des documents dans LibreOffice sous forme de courriel, éventuellement par publipostage, à vos contacts téléphoniques.

Elle fournit en plus une API permettant d’envoyer des courriels en BASIC et supportant les technologies les plus avancées: protocole OAuth2, Mozilla IspDB, HTTP au lieu de SMTP/IMAP pour les serveurs Google… Une macro SendEmail permettant d’envoyer des courriels est fournie à titre d’exemple.
Si au préalable vous ouvrez un document, vous pouvez la lancer par:
Outils -> Macros -> Exécuter la macro… -> Mes macros -> eMailerOOo -> SendEmail -> Main -> Exécuter

Etant un logiciel libre je vous encourage:

• A dupliquer son code source.
• A apporter des modifications, des corrections, des améliorations.
• D’ouvrir un dysfonctionnement si nécessaire.

Bref, à participer au developpement de cette extension.
Car c’est ensemble que nous pouvons rendre le Logiciel Libre plus intelligent.

---

Prérequis:

L’extension eMailerOOo utilise l’extension OAuth2OOo pour fonctionner.
Elle doit donc répondre aux prérequis de l’extension OAuth2OOo.

L’extension eMailerOOo utilise l’extension jdbcDriverOOo pour fonctionner.
Elle doit donc répondre aux prérequis de l’extension jdbcDriverOOo.

Sous Linux et macOS les paquets Python utilisés par l’extension, peuvent s’il sont déja installé provenir du système et donc, peuvent ne pas être à jour.
Afin de s’assurer que vos paquets Python sont à jour il est recommandé d’utiliser l’option Info système dans les Options de l’extension accessible par:
Outils -> Options -> Internet -> eMailerOOo -> Voir journal -> Info système
Si des paquets obsolètes apparaissent, vous pouvez les mettre à jour avec la commande:
pip install --upgrade <package-name>

Pour plus d’information voir: Ce qui a été fait pour la version 1.2.0.

---

Installation:

Il semble important que le fichier n’ait pas été renommé lors de son téléchargement.
Si nécessaire, renommez-le avant de l’installer.

• Installer l’extension OAuth2OOo.oxt

  Vous devez d’abord installer cette extension, si elle n’est pas déjà installée.

• Installer l’extension jdbcDriverOOo.oxt

  Cette extension est nécessaire pour utiliser HsqlDB version 2.7.2 avec toutes ses fonctionnalités.

• Si vous n’avez pas de source de données, vous pouvez:

  • Installer l’extension vCardOOo.oxt

    Cette extension n’est nécessaire que si vous souhaitez utiliser vos contacts présents sur une plateforme Nextcloud comme source de données pour les listes de diffusion et la fusion de documents.

  • Installer l’extension gContactOOo.oxt

    Cette extension n’est nécessaire que si vous souhaitez utiliser vos contacts téléphoniques personnels (contact Android) comme source de données pour les listes de diffusion et la fusion de documents.

  • Installer l’extension mContactOOo.oxt

    Cette extension n’est nécessaire que si vous souhaitez utiliser vos contacts Microsoft Outlook comme source de données pour les listes de diffusion et la fusion de documents.

• Installer l’extension eMailerOOo.oxt

Redémarrez LibreOffice après l’installation.
Attention, redémarrer LibreOffice peut ne pas suffire.

• Sous Windows pour vous assurer que LibreOffice redémarre correctement, utilisez le Gestionnaire de tâche de Windows pour vérifier qu’aucun service LibreOffice n’est visible après l’arrêt de LibreOffice (et tuez-le si ç’est le cas).
• Sous Linux ou macOS vous pouvez également vous assurer que LibreOffice redémarre correctement, en le lançant depuis un terminal avec la commande soffice et en utilisant la combinaison de touches Ctrl + C si après l’arrêt de LibreOffice, le terminal n’est pas actif (pas d’invité de commande).

---

Utilisation:

Introduction:

Pour pouvoir utiliser la fonctionnalité de publipostage de courriels en utilisant des listes de diffusion, il est nécessaire d’avoir une source de données avec des tables ayant les colonnes suivantes:

• Une ou plusieurs colonnes d’adresses électroniques. Ces colonnes sont choisi dans une liste et si ce choix n’est pas unique, alors la première colonne d’adresse courriel non nulle sera utilisée.
• Une ou plusieurs colonnes de clé primaire permettant d’identifier de manière unique les enregistrements, elle peut être une clé primaire composée. Les types supportés sont VARCHAR et/ou INTEGER, ou derivé. Ces colonnes doivent être declarée avec la contrainte NOT NULL.

De plus, cette source de données doit avoir au moins une table principale, comprenant tous les enregistrements pouvant être utilisés lors du publipostage du courriel.

Si vous ne disposez pas d’une telle source de données alors je vous invite à installer une des extensions suivantes :

• vCardOOo. Cette extension vous permettra d’utiliser vos contacts présents sur une plateforme Nextcloud comme source de données.
• gContactOOo. Cette extension vous permettra d’utiliser votre téléphone Android (vos contacts téléphoniques) comme source de données.
• mContactOOo. Cette extension vous permettra d’utiliser vos contacts Microsoft Outlook comme source de données.

Pour ces 3 extensions le nom de la table principale peut être trouvé (et même changé avant toute connexion) dans:
Outils -> Options -> Internet -> Nom de l’extension -> Nom de la table principale

Ce mode d’utilisation est composé de 3 sections:

• Publipostage de courriels avec des listes de diffusion.
• Configuration de la connexion.
• Courriels sortants.

Publipostage de courriels avec des listes de diffusion:

Prérequis:

Pour pouvoir publiposter des courriels suivant une liste de diffusion, vous devez:

• Disposer d’une source de données comme décrit dans l’introduction précédente.
• Ouvrir un nouveau document Writer dans LibreOffice / OpenOffice.

Ce document Writer peut inclure des champs de fusion (insérables par la commande: Insertion -> Champ -> Autres champs -> Base de données -> Champ de publipostage), cela est même nécessaire si vous souhaitez pouvoir personnaliser le contenu du courriel et d’eventuel fichiers attachés.
Ces champs de fusion doivent uniquement faire référence à la table principale de la source de données.

Si vous souhaitez utiliser un document Writer déja existant, vous devez vous assurer en plus que la source de données et la table principale sont bien rattachées au document dans : Outils -> Source du carnet d’adresses….

Si ces recommandations ne sont pas suivies alors la fusion de documents ne fonctionnera pas et ceci silencieusement.

Démarrage de l’assistant de publipostage de courriels:

Dans un document LibreOffice / OpenOffice Writer aller à: Outils -> Add-ons -> Envoi de courriels -> Publiposter un document

Sélection de la source de données:

Le chargement de la source de données de l’assistant Publipostage de courriels devrait apparaître :

Les captures d’écran suivantes utilisent l’extension gContactOOo comme source de données. Si vous utilisez votre propre source de données, il est nécessaire d’adapter les paramètres par rapport à celle-ci.

Dans la copie d’écran suivante, on peut voir que la source de données gContactOOo s’appelle: Adresses et que dans la liste des tables la table: PUBLIC.Tous mes contacts est sélectionnée.

Si aucune liste de diffusion n’existe, vous devez en créer une, en saisissant son nom et en validant avec: ENTRÉE ou le bouton Ajouter.

Assurez-vous lors de la création de la liste de diffusion que la table principale est toujours bien sélectionnée dans la liste des tables.
Si cette recommandation n’est pas suivie alors la fusion de documents ne fonctionnera pas et ceci silencieusement.

Maintenant que votre nouvelle liste de diffusion est disponible dans la liste, vous devez la sélectionner.

Et ajouter les colonnes suivantes:

• Colonne de clef primaire: Uri
• Colonnes d’adresses électronique: HomeEmail, WorkEmail et OtherEmail

Si plusieurs colonnes d’adresses courriel sont sélectionnées, alors l’ordre devient pertinent puisque le courriel sera envoyé à la première adresse disponible.
De plus, à l’étape Sélection des destinataires de l’assistant, dans l’onglet Destinataires disponibles, seuls les enregistrements avec au moins une colonne d’adresse courriel saisie seront répertoriés.
Assurez-vous donc d’avoir un carnet d’adresses avec au moins un des champs d’adresse e-mail (Home, Work ou Other) renseigné.

Ce paramètrage ne doit être effectué que pour les nouvelles listes de diffusion.
Vous pouvez maintenant passer à l’étape suivante.

Sélection des destinataires:

Destinataires disponibles:

Les destinataires sont sélectionnés à l’aide de 2 boutons Tout ajouter et Ajouter permettant respectivement:

• Soit d’ajouter le groupe de destinataires sélectionnés dans la liste Carnet d'adresses. Ceci permet lors d’un publipostage, que les modifications du contenu du groupe soient prises en compte. Une liste de diffusion n’accepte qu’un seul groupe.
• Soit d’ajouter la sélection, qui peut être multiple à l’aide de la touche CTRL. Cette sélection est immuable quelle que soit la modification des groupes du carnet d’adresses.

Example de la sélection multiple:

Destinataires sélectionnés:

Les destinataires sont désélectionnés à l’aide de 2 boutons Tout retirer et Retirer permettant respectivement:

• Soit de retirer le groupe qui a été affecté à cette liste de diffusion. Ceci est nécessaire afin de pouvoir modifier à nouveau le contenu de cette liste de diffusion.
• Soit de retirer la sélection, qui peut être multiple à l’aide de la touche CTRL.

Si vous avez sélectionné au moins 1 destinataire, vous pouvez passer à l’étape suivante.

Sélection des options d’envoi:

Si cela n’est pas déjà fait, vous devez créer un nouvel expéditeur à l’aide du bouton Ajouter.

La création du nouvel expéditeur est décrite dans la section Configuration de la connexion.

Le courriel doit avoir un sujet. Il peut être enregistré dans le document Writer.
Vous pouvez insérer des champs de fusion dans l’objet du courriel. Un champ de fusion est composé d’une accolade ouvrante, du nom de la colonne référencée (sensible à la casse) et d’une accolade fermante (ie: {NomColonne}).

Le courriel peut éventuellement contenir des fichiers joints. Ils peuvent être enregistrés dans le document Writer.
La capture d’écran suivante montre 1 fichier joint qui sera fusionné sur la source de données puis converti au format PDF avant d’être joint au courriel.

Assurez-vous de toujours quitter l’assistant avec le bouton Terminer pour confirmer la soumission des travaux d’envoi.
Pour envoyer les travaux d’envoi, veuillez suivre la section Courriels sortants.

Configuration de la connexion:

Démarrage de l’assistant de connexion:

Dans LibreOffice / OpenOffice aller à: Outils -> Add-ons -> Envoi de courriels -> Configurer la connexion

Sélection du compte:

Trouver la configuration:

Configuration SMTP:

Configuration IMAP:

Tester la connexion:

Assurez-vous de toujours quitter l’assistant avec le bouton Terminer afin d’enregistrer les paramètres de connexion.

Courriels sortants:

Démarrage du spouleur de courriels:

Dans LibreOffice / OpenOffice aller à: Outils -> Add-ons -> Envoi de courriels -> Courriels sortants

Liste des courriels sortants:

Chaque travaux d’envoi possède 3 états différents:

• État 0: le courriel est prêt à être envoyé.
• État 1: le courriel a été envoyé avec succès.
• État 2: Une erreur est survenue lors de l’envoi du courriel. Vous pouvez consulter le message d’erreur dans le Journal d’activité du spouleur.

Le spouleur de courriels est arrêté par défaut. Il doit être démarré avec le bouton Démarrer / Arrêter pour que les courriels en attente soient envoyés.

Journal d’activité du spouleur:

Lorsque le spouleur de courriel est démarré, son activité peut être visualisée dans le journal d’activité.

---

A été testé avec:

• LibreOffice 7.3.7.2 - Lubuntu 22.04 - Python version 3.10.12 - OpenJDK-11-JRE (amd64)

• LibreOffice 7.5.4.2(x86) - Windows 10 - Python version 3.8.16 - Adoptium JDK Hotspot 11.0.19 (under Lubuntu 22.04 / VirtualBox 6.1.38)

• LibreOffice 7.4.3.2(x64) - Windows 10(x64) - Python version 3.8.15 - Adoptium JDK Hotspot 11.0.17 (x64) (under Lubuntu 22.04 / VirtualBox 6.1.38)

• Ne fonctionne pas avec OpenOffice sous Windows voir dysfonctionnement 128569. N’ayant aucune solution, je vous encourrage d’installer LibreOffice.

Je vous encourage en cas de problème
de créer un dysfonctionnement
J’essaierai de le résoudre

---

Historique:

Ce qui a été fait pour la version 0.0.1:

• Ecriture de IspDB ou l’assistant de Configuration de connexion aux serveurs SMTP permettant:
  • De trouver les paramètres de connexion à un serveur SMTP à partir d’une adresse courriel. D’ailleur je remercie particulierement Mozilla, pour Thunderbird autoconfiguration database ou IspDB, qui à rendu ce défi possible…
  • D’afficher l’activité du service UNO com.sun.star.mail.MailServiceProvider lors de la connexion au serveur SMTP et l’envoi d’un courriel.
• Ecriture du Spouleur de courriels permettant:
  • D’afficher les travaux d’envoi de courriel avec leurs états respectifs.
  • D’afficher l’activité du service UNO com.sun.star.mail.SpoolerService lors de l’envoi de courriels.
  • De démarrer et arrêter le service spouleur.
• Ecriture du Merger ou l’assistant de publipostage de courriels permettant:
  • De créer des listes de diffusions.
  • De fusionner et convertir au format HTML le document courant pour en faire le message du courriel.
  • De fusionner et/ou convertir au format PDF d’éventuel fichiers joints au courriel.
• Ecriture du Mailer de document permettant:
  • De convertir au format HTML le document pour en faire le message du courriel.
  • De convertir au format PDF d’éventuel fichiers joints au courriel.
• Ecriture d’un Grid piloté par un com.sun.star.sdb.RowSet permettant:
  • D’être paramètrable sur les colonnes à afficher.
  • D’être paramètrable sur l’ordre de tri à afficher.
  • De sauvegarder les paramètres d’affichage.

Ce qui a été fait pour la version 0.0.2:

• Réécriture de IspDB ou Assistant de configuration de connexion aux serveurs de messagerie afin d’intégrer la configuration de la connexion IMAP.
  • Utilisation de IMAPClient version 2.2.0: une bibliothèque cliente IMAP complète, Pythonic et facile à utiliser.
  • Extension des fichiers IDL com.sun.star.mail.*:
    • XMailMessage2.idl prend désormais en charge la hiérarchisation des courriels (thread).
    • La nouvelle interface XImapService permet d’accéder à une partie de la bibliothèque IMAPClient.

• Réécriture du Spouleur afin d’intégrer des fonctionnalités IMAP comme la création d’un fil récapitulant le publipostage et regroupant tous les courriels envoyés.

• Soumission de l’extension eMailerOOo à Google et obtention de l’autorisation d’utiliser son API GMail afin d’envoyer des courriels avec un compte Google.

Ce qui a été fait pour la version 0.0.3:

• Réécriture du Grid afin de permettre:
  • Le tri sur une colonne avec l’intégration du service UNO SortableGridDataModel.
  • La génération des filtres des enregistrements nécessaires au service Spouleur.
  • Le partage avec le module python Grid de l’extension jdbcDriverOOo.
• Réécriture du Merger afin de permettre:
  • La gestion du nom du Schema dans de nom des tables afin d’être compatible avec la version 0.0.4 de jdbcDriverOOo.
  • La création de liste de diffusion sur un groupe du carnet d’adresse et permettant de suivre la modification de son contenu.
  • L’utilisation de clé primaire, qui peuvent être composite, supportant les DataType VARCHAR et INTEGER ou derivé.
  • Un aperçu du document avec des champs de fusion remplis plus rapidement grâce au Grid.
• Réécriture du Spouleur afin de permettre:
  • L’utilisation des nouveaux filtres supportant les clés primaires composite fourni par le Merger.
  • L’utilisation du nouveau Grid permettant le tri sur une colonne.
• Encore plein d’autres choses…

Ce qui a été fait pour la version 1.0.0:

• L’extension smtpMailerOOo a été renomé en eMailerOOo.

Ce qui a été fait pour la version 1.0.1:

• L’absence ou l’obsolescence des extensions OAuth2OOo et/ou jdbcDriverOOo nécessaires au bon fonctionnement de eMailerOOo affiche désormais un message d’erreur. Ceci afin d’éviter qu’un dysfonctionnement tel que le dysfonctionnement #3 ne se reproduise…

• La base de données HsqlDB sous-jacente peut être ouverte dans Base avec: Outils -> Options -> Internet -> eMailerOOo -> Base de données.

• Le menu Outils -> Add-ons s’affiche désormais correctement en fonction du contexte.

• Encore plein d’autres choses…

Ce qui a été fait pour la version 1.0.2:

• Si aucune configuration n’est trouvée dans l’assistant de configuration de la connexion (IspDB Wizard) alors il est possible de configurer la connexion manuellement. Voir dysfonctionnement #5.

Ce qui a été fait pour la version 1.1.0:

• Dans l’assistant de configuration de la connexion (IspDB Wizard) il est maintenant possible de désactiver la configuration IMAP.
  En conséquence, cela n’envoie plus de fil de discussion (message IMAP) lors de la fusion d’un mailing.
  Dans ce même assistant, il est désormais possible de saisir une adresse courriel de réponse.

• Dans l’assistant de fusion d’email, il est désormais possible d’insérer des champs de fusion dans l’objet du courriel. Voir dysfonctionnement #6.
  Dans le sujet d’un courriel, un champ de fusion est composé d’une accolade ouvrante, du nom de la colonne référencée (sensible à la casse) et d’une accolade fermante (ie: {NomDeLaColonne}).
  Lors de la saisie du sujet du courriel, une erreur de syntaxe dans un champ de fusion sera signalée et empêchera la soumission du mailing.

• Il est désormais possible dans le Spooler de visualiser les courriels au format eml.

• Un service com.sun.star.mail.MailUser permet désormais d’accéder à une configuration de connexion (SMTP et/ou IMAP) depuis une adresse courriel qui suite la rfc822.
  Un autre service com.sun.star.datatransfer.TransferableFactory permet, comme son nom l’indique, la création de Transferable à partir d’un texte (string), d’une séquence binaire, d’une Url (file://…) ou un flux de données (InputStream).
  Ces deux nouveaux services simplifient grandement l’API mail de LibreOffice et permettent d’envoyer des courriels depuis Basic. Voir le dysfonctionnement #4.
  Vous trouverez une macro Basic vous permettant d’envoyer des emails dans : Outils -> Macros -> Editer les Macros… -> eMailerOOo -> SendEmail.

Ce qui a été fait pour la version 1.1.1:

• Prise en charge de la version 1.2.0 de l’extension OAuth2OOo. Les versions précédentes ne fonctionneront pas avec l’extension OAuth2OOo 1.2.0 ou ultérieure.

Ce qui a été fait pour la version 1.2.0:

• Tous les paquets Python nécessaires à l’extension sont désormais enregistrés dans un fichier requirements.txt suivant la PEP 508.
• Désormais si vous n’êtes pas sous Windows alors les paquets Python nécessaires à l’extension peuvent être facilement installés avec la commande:
  pip install requirements.txt
• Modification de la section Prérequis.

Ce qui a été fait pour la version 1.2.1:

• Correction d’une régression permettant l’affichage des erreurs dans le Spooler.
• Intégration d’un correctif pour contourner le dysfonctionnement #159988.

Ce qui a été fait pour la version 1.2.2:

• La création de la base de données, lors de la première connexion, utilise l’API UNO proposée par l’extension jdbcDriverOOo depuis la version 1.3.2. Cela permet d’enregistrer toutes les informations nécessaires à la création de la base de données dans 5 tables texte qui sont en fait 5 fichiers csv.
• L’extension vous demandera d’installer les extensions OAuth2OOo et jdbcDriverOOo en version respectivement 1.3.4 et 1.3.2 minimum.
• De nombreuses corrections.

Que reste-t-il à faire pour la version 1.2.2:

• Ajouter de nouvelles langues pour l’internationalisation…

• Tout ce qui est bienvenu…