|
| 1 | +--- |
| 2 | +lang: fr-FR |
| 3 | +title: Templates de mails |
| 4 | +description: Configuration, conventions et utilisation des modèles Handlebars pour l'envoi de courriels dans Sesame-Orchestrator |
| 5 | +--- |
| 6 | + |
| 7 | +# Templates de mails |
| 8 | + |
| 9 | +Sesame-Orchestrator utilise des fichiers **Handlebars** (`.hbs`) pour le rendu HTML des courriels. Ils servent aux flux automatiques (invitation, reset, rappels d’expiration, alertes) et à l’**envoi manuel** depuis la table des identités. |
| 10 | + |
| 11 | +## Emplacements des fichiers |
| 12 | + |
| 13 | +| Élément | Chemin (dans le conteneur API) | Rôle | |
| 14 | +| --- | --- | --- | |
| 15 | +| Templates HTML | `templates/*.hbs` | Modèles Handlebars compilés à l’envoi | |
| 16 | +| Variables UI | `configs/mail/mail_templates.yml` | Variables proposées dans la modale d’envoi manuel | |
| 17 | +| Valeurs par défaut | `defaults/mail/mail_templates.yml` | Copié vers `configs/mail/` au premier démarrage si absent | |
| 18 | + |
| 19 | +En déploiement Docker, monter le répertoire des templates sur `/data/templates` (voir aussi [Configuration gestion MDP](config-gestion-mdp.html#modele-des-mails)). |
| 20 | + |
| 21 | +Exemple de volume : |
| 22 | + |
| 23 | +```yaml |
| 24 | +- ./configs/sesame-orchestrator/templates:/data/templates |
| 25 | +``` |
| 26 | +
|
| 27 | +Le fichier `configs/mail/mail_templates.yml` peut être monté ou versionné séparément selon votre installation. |
| 28 | + |
| 29 | +## Types de templates |
| 30 | + |
| 31 | +### Templates personnalisables (`mail_*`) |
| 32 | + |
| 33 | +Les fichiers dont le nom commence par **`mail_`** sont listés en priorité et peuvent être **envoyés manuellement** depuis l’interface (identités synchronisées). |
| 34 | + |
| 35 | +Exemples fournis : |
| 36 | + |
| 37 | +| Fichier | Usage typique | |
| 38 | +| --- | --- | |
| 39 | +| `mail_welcome.hbs` | Message de bienvenue | |
| 40 | +| `mail_custom_notification.hbs` | Notification générique (titre, message, CTA) | |
| 41 | +| `mail_security_alert.hbs` | Alerte sécurité (ex. mot de passe compromis) | |
| 42 | + |
| 43 | +### Templates internes Sesame (sans préfixe `mail_`) |
| 44 | + |
| 45 | +Réservés aux **flux métier** de la plateforme. Ils apparaissent dans la liste de la modale d’envoi en **mode lecture seule** (aperçu uniquement) : |
| 46 | + |
| 47 | +| Fichier | Déclenché par | |
| 48 | +| --- | --- | |
| 49 | +| `initaccount.hbs` | Invitation / initialisation de compte (`POST /management/passwd/init`, `initmany`) | |
| 50 | +| `resetaccount.hbs` | Réinitialisation de mot de passe (`PasswdService`, code à 6 chiffres) | |
| 51 | + |
| 52 | +L’API refuse l’envoi manuel de ces templates (`POST /management/mail/sendmany`). |
| 53 | + |
| 54 | +## Moteur de rendu |
| 55 | + |
| 56 | +- **Moteur** : [Handlebars](https://handlebarsjs.com/) (via `@nestjs-modules/mailer`). |
| 57 | +- **Mode strict** : activé à l’**envoi réel** (variable absente = erreur). |
| 58 | +- **Aperçu UI** : mode non strict + valeurs fictives pour les variables runtime non connues à l’avance (ex. `code` de reset). |
| 59 | + |
| 60 | +Syntaxe courante : `{{ variable }}`, blocs `{{#if variable}}…{{/if}}`, accès imbriqué `{{ identity.inetOrgPerson.uid }}`. |
| 61 | + |
| 62 | +### Variables courantes par flux |
| 63 | + |
| 64 | +**Initialisation (`initaccount`)** — fournies par le backend : |
| 65 | + |
| 66 | +| Variable | Description | |
| 67 | +| --- | --- | |
| 68 | +| `uid` | Identifiant du compte | |
| 69 | +| `url` | Lien d’activation (token) | |
| 70 | +| `displayName` | Nom affiché | |
| 71 | +| `mail` | Adresse mail de l’identité | |
| 72 | + |
| 73 | +**Reset (`resetaccount`)** : |
| 74 | + |
| 75 | +| Variable | Description | |
| 76 | +| --- | --- | |
| 77 | +| `displayName` | Nom affiché | |
| 78 | +| `uid` | Identifiant | |
| 79 | +| `code` | Code numérique de réinitialisation (généré à l’envoi, non prédictible en aperçu) | |
| 80 | + |
| 81 | +**Envoi manuel (`mail_*`)** — selon le template ; l’objet **`identity`** (document MongoDB) est injecté dans le contexte, ainsi que les variables de `mail_templates.yml` et les variables additionnelles saisies dans la modale. |
| 82 | + |
| 83 | +Le **sujet SMTP** est un champ **obligatoire** saisi dans l’UI (ou fixé par le flux automatique), distinct des variables Handlebars du corps (sauf si le template réutilise `{{ subject }}` dans le HTML). |
| 84 | + |
| 85 | +### Aperçu : valeurs par défaut |
| 86 | + |
| 87 | +Lors d’un aperçu, des placeholders sont appliqués si la variable n’est pas fournie, par exemple : |
| 88 | + |
| 89 | +- `code` → `123456` |
| 90 | +- `url` → `https://example.invalid/preview` |
| 91 | +- `displayName` → `Jean Dupont (aperçu)` |
| 92 | +- `uid` → `preview.user` |
| 93 | + |
| 94 | +Les variables additionnelles saisies dans la modale **remplacent** ces défauts. |
| 95 | + |
| 96 | +## Configuration `mail_templates.yml` |
| 97 | + |
| 98 | +Fichier : `configs/mail/mail_templates.yml` |
| 99 | + |
| 100 | +```yaml |
| 101 | +mailTemplates: |
| 102 | + variables: |
| 103 | + - key: appName |
| 104 | + label: Nom de l'application |
| 105 | + description: Nom affiché dans certains templates. |
| 106 | + example: "Sesame" |
| 107 | + defaultValue: "Sesame" |
| 108 | + - key: url |
| 109 | + label: URL principale |
| 110 | + ... |
| 111 | +``` |
| 112 | + |
| 113 | +- Les entrées alimentent la section **« Variables pré-construites »** de la modale. |
| 114 | +- Les `defaultValue` peuvent contenir des placeholders **Liquid** `{{ ... }}` résolus au chargement (`resolveConfigVariables`). |
| 115 | +- Le **sujet** n’y figure plus : il est saisi dans un champ dédié de la modale. |
| 116 | + |
| 117 | +Pour ajouter une variable disponible côté UI, ajoutez une entrée `key` / `label` / `defaultValue`, puis redémarrez ou rechargez la config selon votre déploiement. |
| 118 | + |
| 119 | +## Chemins JSON des destinataires (SMTP) |
| 120 | + |
| 121 | +Configurés dans **Paramètres → Serveur SMTP** (`/settings/smtp`) : |
| 122 | + |
| 123 | +| Champ | Exemple | |
| 124 | +| --- | --- | |
| 125 | +| Chemin JSON — e-mail principal | `inetOrgPerson.mail` | |
| 126 | +| Chemin JSON — e-mail personnel | `additionalFields.attributes.supannPerson.supannAutreMail` | |
| 127 | + |
| 128 | +Ces chemins sont **validés à l’enregistrement** sur une identité synchronisée. |
| 129 | + |
| 130 | +Lors de l’envoi manuel, l’utilisateur peut sélectionner **une ou plusieurs** adresses (principal et/ou personnel). Pour chaque identité, les adresses distinctes reçoivent **un même message** (champ `to` multiple). Les adresses vides sur un chemin sont ignorées ; si aucune adresse n’est trouvée, l’identité est comptée comme « ignorée » (`skipped`). |
| 131 | + |
| 132 | +## API de gestion des templates |
| 133 | + |
| 134 | +Préfixe : `/management/mail` |
| 135 | + |
| 136 | +| Méthode | Route | Description | |
| 137 | +| --- | --- | --- | |
| 138 | +| `GET` | `/templates` | Liste tous les fichiers `.hbs` (tri : `mail_*` en premier) | |
| 139 | +| `GET` | `/templates/config` | Contenu de `mail_templates.yml` (variables UI) | |
| 140 | +| `POST` | `/templates/preview` | Rendu HTML d’aperçu (`template`, `variables` optionnelles) | |
| 141 | +| `POST` | `/sendmany` | Envoi d’un template à plusieurs identités synchronisées | |
| 142 | + |
| 143 | +### Corps de `POST /sendmany` |
| 144 | + |
| 145 | +```json |
| 146 | +{ |
| 147 | + "ids": ["…"], |
| 148 | + "template": "mail_welcome", |
| 149 | + "subject": "Bienvenue sur Sesame", |
| 150 | + "variables": { |
| 151 | + "appName": "Sesame", |
| 152 | + "url": "https://…" |
| 153 | + }, |
| 154 | + "recipientAddressSources": ["principal", "personnel"] |
| 155 | +} |
| 156 | +``` |
| 157 | + |
| 158 | +- `template` : nom sans extension `.hbs`, doit commencer par `mail_` pour l’envoi manuel. |
| 159 | +- `subject` : obligatoire. |
| 160 | +- `recipientAddressSources` : tableau non vide ; valeurs `principal` et/ou `personnel`. Si absent, repli sur l’attribut mail de la politique de mot de passe (`emailAttribute`). |
| 161 | + |
| 162 | +Réponse : `{ "sent": n, "skipped": m }`. |
| 163 | + |
| 164 | +## Interface : envoi depuis les identités |
| 165 | + |
| 166 | +Disponible pour les identités **synchronisées** uniquement : |
| 167 | + |
| 168 | +- **Liste** `/identities/table` : action de masse « Envoyer un mail (template) » (`mdi-email`). |
| 169 | +- **Fiche** `/identities/table/:id` : même action sur une identité. |
| 170 | + |
| 171 | +La modale permet de : |
| 172 | + |
| 173 | +1. Choisir un template (aperçu à droite). |
| 174 | +2. Saisir le **sujet** (obligatoire pour les templates `mail_*`). |
| 175 | +3. Choisir une ou plusieurs **adresses destinataires** (si configurées dans SMTP). |
| 176 | +4. Ajuster les variables pré-construites et des variables libres (clé/valeur). |
| 177 | +5. Optionnellement envoyer à toute la sélection filtrée (case à cocher si plusieurs identités éligibles). |
| 178 | + |
| 179 | +Templates internes : bandeau « mode lecture seule », pas d’envoi, champs sujet/destinataire masqués. |
| 180 | + |
| 181 | +Permissions : envoi soumis aux droits sur `/management/identities` (mise à jour) et `/management/mail` (création). |
| 182 | + |
| 183 | +## Créer un template `mail_*` personnalisé |
| 184 | + |
| 185 | +1. Ajouter `templates/mail_mon_message.hbs` (préfixe `mail_` obligatoire pour l’envoi manuel). |
| 186 | +2. Utiliser Handlebars ; tester avec l’aperçu dans la modale. |
| 187 | +3. Optionnel : déclarer des variables dans `configs/mail/mail_templates.yml`. |
| 188 | +4. Redémarrer l’API si les templates sont lus au démarrage selon votre configuration Mailer. |
| 189 | + |
| 190 | +Conseil MJML : composer en [MJML](https://mjml.io/), exporter en HTML, enregistrer dans le fichier `.hbs` (voir [config gestion MDP](config-gestion-mdp.html#faire-son-modele-de-mail)). |
| 191 | + |
| 192 | +## Rappels d’expiration et cron |
| 193 | + |
| 194 | +Les jalons de rappel de mot de passe (politique MDP + cron `identities-password-expiration-reminder`) utilisent des templates `mail_*` configurés dans `passwordExpirationReminderSteps`. Voir [Politique mots de passe](../pages/settings/password-policy.html) et [Tâches planifiées](cron.html). |
| 195 | + |
| 196 | +## Voir aussi |
| 197 | + |
| 198 | +- [Serveur SMTP](../pages/settings/smtp.html) — paramètres SMTP et chemins JSON destinataires |
| 199 | +- [Table des identités](../pages/identities/table.html) — actions de masse |
| 200 | +- [Configuration gestion MDP](config-gestion-mdp.html) — montage Docker et création graphique (MJML) |
0 commit comments