Aller au contenu

Code source wiki de 01 - Documentation technique

Version 56.1 par Matthieu Manginot le 07/03/2022 - 14:22
Masquer les derniers auteurs
Cédric Champmartin 9.1 1
2
3 {{toc/}}
4
Cédric Champmartin 2.1 5 == Prérequis ==
6
Matthieu Manginot 10.1 7 * Hypercerts est une application Java qui se connecte à Apogée et au LDAP.
8 * Elle requiert l'utilisation d'une base MariaDB pour son fonctionnement interne.
9 * Elle se déploie sur des serveurs comme une application SpringBoot classique.
Cédric Champmartin 2.1 10
11 |=(((
12 Technologie
13 )))|=(((
14 Version
15 )))
16 |(((
17 JDK
18 )))|(((
19 11+
20 )))
21 |(% colspan="1" %)(((
22 SpringBoot
23 )))|(% colspan="1" %)(((
24 2.3
25 )))
26 |(% colspan="1" %)(((
27 Vaadin (Frontend)
28 )))|(% colspan="1" %)(((
29 14
30 )))
31 |(((
32 Tomcat
33 )))|(((
34 9+
35 )))
36 |(% colspan="1" %)(((
37 MariaDB
38 )))|(% colspan="1" %)(((
39 14+
40 )))
41 |(% colspan="1" %)(((
42 Maven
43 )))|(% colspan="1" %)(((
44 3.6+
45 )))
46 |(% colspan="1" %)(((
47 Connection Apogée
48 )))|(% colspan="1" %)(((
Cédric Champmartin 1.1 49 \\
Cédric Champmartin 2.1 50 )))
51 |(% colspan="1" %)(((
52 Connection LDAP
53 )))|(% colspan="1" %)(((
54 \\
55 )))
56
57 == Téléchargement des sources ==
58
Matthieu Manginot 56.1 59 * Pour WS Apogée 6.20.70 : [[hypercerts-1.0.5.8-SNAPSHOT.zip>>url:https://download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.5.8-SNAPSHOT.zip||shape="rect"]]
60 * Précédentes versions : 
61 ** Pour WS Apogée 6.10.02 et plus : [[hypercerts-1.0.5.7-SNAPSHOT.zip>>url:https://download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.5.7-SNAPSHOT.zip||shape="rect"]]
62 ** Pour les WS Apogée 6.10.00 : [[hypercerts-1.0.5.4-SNAPSHOT.zip>>url:https://download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.5.4-SNAPSHOT.zip||style="letter-spacing: 0.0px;" shape="rect"]]
Cédric Champmartin 2.1 63
64 == Installation d'Hypercerts ==
65
Matthieu Manginot 27.1 66 === **Initialisation / Mise à jour de la base** ===
Cédric Champmartin 2.1 67
Matthieu Manginot 39.1 68 La base **hypercerts **MariaDB/MySQL s'initialise / se met à jour avec la commande **Flyway** suivante :
Cédric Champmartin 2.1 69
70 {{code language="bash" theme="Eclipse"}}
71 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
72 {{/code}}
73
Matthieu Manginot 33.1 74 Le fichier **flyway.properties doit être créé** à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
Cédric Champmartin 2.1 75
76 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
77 # Flyway
78 # ConfigFiles : https://flywaydb.org/documentation/configfiles
79 # mvn -Dflyway.configFiles=xxx.properties flyway:migrate
80 flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
81 flyway.schemas=hypercerts
82 flyway.user=XXX
83 flyway.password=
84 # Emplacement des fichiers sql de migration
85 flyway.locations=classpath:db/migration
86 # baselineOnMigrate
87 flyway.baselineOnMigrate=false
88 {{/code}}
89
Matthieu Manginot 36.1 90 Au besoin, les fichiers sql de migration peuvent être trouvés sous **src/main/resources/db/migration**.
Cédric Champmartin 2.1 91
Matthieu Manginot 39.1 92 Pour remettre à zéro la base de données **hypercerts**, lancer le script **src/main/resources/db/reset/reset.sql// //**puis exécuter à nouveau **Flyway**//.//
Cédric Champmartin 2.1 93
94 === Configuration de l'application ===
95
96 Créer et compléter un fichier **application.yaml** à la racine du projet sur le modèle de **application-sample.yaml**
97
Matthieu Manginot 33.1 98 Des indications sont présentes dans le fichier pour aider à sa configuration ou **ci-dessous**.
Cédric Champmartin 2.1 99
Matthieu Manginot 33.1 100 === Maven / Exécution de l'application ===
Cédric Champmartin 2.1 101
Matthieu Manginot 39.1 102 * **Sous un** **IDE**, exemple Eclipse//, //**avec le fichier de configuration à la racine** :
Matthieu Manginot 33.1 103 ** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
Matthieu Manginot 39.1 104 * Lancer l'application (**hors d'un IDE**),// //**avec fichier de configuration à la racine** :
Matthieu Manginot 32.1 105
Matthieu Manginot 33.1 106 {{code language="bash" theme="Eclipse"}}
107 mvn spring-boot:run
108 {{/code}}
Matthieu Manginot 32.1 109
Matthieu Manginot 33.1 110 * Lancer les tests :
Matthieu Manginot 32.1 111
Matthieu Manginot 33.1 112 {{code language="bash" theme="Eclipse"}}
113 mvn verify
114 {{/code}}
Matthieu Manginot 32.1 115
Matthieu Manginot 33.1 116 * Créer le package pour production :
117
118 {{code language="bash" theme="Eclipse"}}
119 mvn clean package -Pproduction
120 {{/code}}
121
122 * Sous un serveur, comme Tomcat, le fichier de config peut être déposé à la racine du tomcat avec précision de son emplacement via les options JAVA, exemple :
123
124 {{code language="bash" theme="Eclipse"}}
125 export JAVA_OPTS="$JAVA_OPTS -Dspring.config.location=$HOMEDIR/application.yaml"
126 {{/code}}
127
Matthieu Manginot 36.1 128 == (% style="letter-spacing: -0.006em;" %)**Configuration**(%%) ==
Matthieu Manginot 33.1 129
Matthieu Manginot 34.1 130 === Property //app.production// ===
Cédric Champmartin 2.1 131
Matthieu Manginot 39.1 132 Pour les tests, mettre **app.production** à **//false// **pour obtenir une année supplémentaire (N-2) pour la génération, ainsi des diplômes avec résultats seront plus facilement trouvables.
Cédric Champmartin 2.1 133
Matthieu Manginot 49.1 134 En étant à **false**, cette **property **autorise également la configuration de l'**interception globale de tous les mails applicatifs**.
Cédric Champmartin 2.1 135
136 ==== **Envoi de mail** ====
137
138 (% style="color: rgb(0,51,102);" %)__**Sur votre environnement de test/développement**, pour empêcher l'envoi de mails de test en réel, il est conseillé :__
139
140 * d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/||shape="rect"]]) en remplacement de votre smtp
Matthieu Manginot 47.1 141 * **ou** de configurer l'application pour intercepter globalement tous les **mails applicatifs** avec ces valeurs :
Matthieu Manginot 13.1 142 ** **app.production** à //false//
143 ** **spring.mail.intercept.active** à //true//
Cédric Champmartin 2.1 144 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
Matthieu Manginot 49.1 145 ** Pour éviter l'envoi de **mails Digiposte de test en réel**, il conviendra de renseigner : **spring.mail.intercept.mailDigiposte** avec une adresse mail / liste
Cédric Champmartin 2.1 146
Matthieu Manginot 36.1 147 Enfin, la property **app.mails** sert à définir une ou plusieurs adresses permettant de recevoir les mails applicatifs. ⚠ Aujourd'hui, dans cette version tous les envois de mails ont en copie de cette property. Elle est optionnelle et peut être laissée à vide.
Cédric Champmartin 2.1 148
Matthieu Manginot 42.1 149 === Envoi des attestations aux étudiants ===
150
151 Les attestations peuvent être envoyées aux étudiants par **mail** __**et/ou**__ sur **Digiposte**.
152
153 Pour **activer l'envoi par mail**, mettre la property **app.useMailDelivery** à true.
154
155 Pour **activer l'envoi sur Digiposte**, mettre la property **app.usingDigiposteDelivery** à true.
156
157 Il est possible de **modifier le comportement par défaut** de l'application au moment de la création des campagnes, en activant la property **app.overrideDeliveryOnGeneration**.
158
159 Ce qui affichera le choix suivant dans l'interface pour **tous les gestionnaires** :
160
161 [[image:attach:image2021-3-19_12-1-4.png||width="1020"]]
162
Matthieu Manginot 34.1 163 === WebServices Apogée ===
Cédric Champmartin 2.1 164
165 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
166
Matthieu Manginot 36.1 167 Les **properties **différent du classique fichier de configuration **configUrlServices.properties** de l'AMUE.
Cédric Champmartin 2.1 168
Matthieu Manginot 36.1 169 Des **headers **peuvent être ajoutés en paramètre de chaque WebServices.
Cédric Champmartin 2.1 170
171 Exemple :
172
173 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
174 ws:
175 apogee:
176 administratif:
177 url: https://api.univ.fr/apo/amue_apo_administratif
178 headers:
179 # header1: value1
180 # header2: value2
181 username: xxxx
182 password: xxxx
183 {{/code}}
184
Matthieu Manginot 35.1 185 === Customisation des templates de mail ===
186
Matthieu Manginot 37.1 187 Les properties suivantes servent à indiquer les templates personnalisés :
Matthieu Manginot 35.1 188
Matthieu Manginot 37.1 189 * spring.mail.templateName.**attestation** : pour le mail à destination de l'étudiant contenant l'attestation
190 * spring.mail.templateName.**creationDigiposte** : pour le mail à destination de l'étudiant envoyé après la création du coffre Digiposte
191 * spring.mail.templateName.**creationCampagne** : pour le mail d'une nouvelle campagne (à destination du gestionnaire qui a lancé la campagne)
192 * spring.mail.templateName.**reportCampagne** : pour le mail de rapport de campagne (à destination du gestionnaire qui a lancé la campagne)
193
Matthieu Manginot 50.1 194 {{info}}
195 Par défaut, les valeurs sont vides et les templates par défaut de l'application sont utilisés
196 {{/info}}
Matthieu Manginot 37.1 197
Matthieu Manginot 38.1 198 Pour customiser un template :
199
200 * **Copier et renommer un template HTML** présent sous **src/main/resources/templates**
201 * Par exemple pour le mail d'attestation :
202 ** Renommer** mail-attestation.html** en **mail-attestation-custom.html**
203 ** Adapter le template
204 ** Dans la config, saisir spring.mail.templateName.**attestation **: **mail-attestation-custom.html**
205
Cédric Champmartin 2.1 206 === Customisation des services ===
207
208 Plusieurs services sont personnalisables en fonction de votre environnement.
209
Matthieu Manginot 36.1 210 Sous **fr.univlorraine.hypercerts.apogee.service.customs** :
Cédric Champmartin 2.1 211
Matthieu Manginot 36.1 212 * **ApogeeUtilisateurServiceCustomExample//
213 //**
Matthieu Manginot 25.1 214 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
Matthieu Manginot 36.1 215 * **ApogeeBlocageServiceCustomExample//
216 //**
Cédric Champmartin 2.1 217 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
Matthieu Manginot 36.1 218 * **ApogeeComposanteServiceCustomExample//
219 //**
Cédric Champmartin 2.1 220 ** Personnalisation de la récupération :
Matthieu Manginot 15.1 221 *** de toutes les composantes 
222 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
Matthieu Manginot 25.1 223 *** des composantes pour un utilisateur à partir de l'uid Apogée
224 *** du nombre de composantes pour un utilisateur à partir de l'uid Apogée
Matthieu Manginot 36.1 225 * **ApogeeUidServiceCustomExample**\\
Matthieu Manginot 25.1 226 ** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
Cédric Champmartin 2.1 227
Matthieu Manginot 15.1 228 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
Cédric Champmartin 2.1 229
230 1. Copier la classe en la renommant
231 1. Implémenter la ou les méthodes
232 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
233 1. (((
234 Dé-commenter les 2 annotations :1. (((
Matthieu Manginot 36.1 235 **@Service** → Pour que Spring implémente le Service au démarrage
Cédric Champmartin 2.1 236 )))
237 1. (((
Matthieu Manginot 36.1 238 et **@OverrideXXX** → Pour que l'implémentation surcharge le service par défaut
Cédric Champmartin 2.1 239 )))
240 )))
241 1. Au démarrage de l'application
242 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
Matthieu Manginot 25.1 243 1. Sans IDE, penser à ajouter les imports suivant :
244 11. import org.springframework.stereotype.Service;
Matthieu Manginot 37.1 245 11. import fr.univlorraine.hypercerts.apogee.services.annotations.**OverrideXXX**;
Matthieu Manginot 15.1 246 \\
Cédric Champmartin 2.1 247
Matthieu Manginot 15.1 248 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
Cédric Champmartin 2.1 249 /**
Matthieu Manginot 26.1 250 * Override default ApogeeUtilisateurService implementation.
Cédric Champmartin 2.1 251 * >> README
Matthieu Manginot 26.1 252 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUtilisateurService pour que l'implémentation soit utilisée.
Cédric Champmartin 2.1 253 *
254 * @author Matthieu Manginot
255 */
256 @NoArgsConstructor
257 @Slf4j
Matthieu Manginot 26.1 258 // @Service
259 // @OverrideApogeeUtilisateurService
260 public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
Cédric Champmartin 2.1 261
262 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
263 private EntityManager entityManagerApogee;
264
265 @PostConstruct
266 public void init() {
Matthieu Manginot 26.1 267 log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
Cédric Champmartin 2.1 268 }
269
270 /**
Matthieu Manginot 26.1 271 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
Cédric Champmartin 2.1 272 */
273 @Override
Matthieu Manginot 26.1 274 public String getMail(final String uidApogee) {
275 /* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
276 return null;
Cédric Champmartin 2.1 277 }
278 }
279 {{/code}}
280
Matthieu Manginot 40.1 281 === Configuration de Digiposte ===
Cédric Champmartin 2.1 282
Matthieu Manginot 40.1 283 Dans **application.yaml** sous **digiposte.***
284
285 * **digiposte**
286 ** **codeDistributeur** : Code distributeur Digiposte (fourni par Digiposte)
287 ** **codeEmetteur** : Code emetteur Digiposte (PID) (fourni par Digiposte)
288 ** **type** : Type de campagne : en mode OPT-IN = PREINSCRIPTION ou mode OPT-OUT = PREINSCRIPTION_WITH_VALIDATED_MEMBERSHIP (param Digiposte)
289 ** **sendMailHypercerts** : Envoi du mail Hypercerts pour informer l'étudiant qu'un coffre Digiposte est crée
290 ** **docDigiposteEtudiant** : Url de la documentation Digiposte pour les étudiants présente dans le mail d'information
291 ** **sendMailDigiposte** : Envoi du mail Digiposte : 'YES' ou 'NO' (param Digiposte)
292 ** **checkMailMode** : Vérification du mail : mail vérifié par l'émetteur = CHECKED ou mail non vérifié = INFORMATION (param Digiposte)
293 ** **urlAccesDirect** : Urls d'accès direct à Digiposte pour les adhésions ou les résiliations\\
294 *** **adhesions** : Url pour les adhésions directes
295 *** **resiliations** : Url pour les résiliations directes
296 ** **adhesions** : Configuration de l'envoi des adhésions (création des coffres)\\
297 *** **ftp** : Connexion au sftp Digiposte des adhésions
298 *** **ws** : Connexion au ws Digiposte
299 ** **routages** : Configuration de l'envoi des routages (dépôt des attestations dans les coffres)
300 *** **ftp **: Connexion au sftp Digiposte des routages
Matthieu Manginot 49.1 301 *** (% style="letter-spacing: 0.0px;" %)**publisher**(%%) : Configuration du publisher : Clé publique pour la sécurisation des routages
Matthieu Manginot 40.1 302
Matthieu Manginot 49.1 303
304 Egalement, pour éviter l'envoi de (% style="letter-spacing: 0.0px;" %)**mails Digiposte de test en réel**(%%), il faudra activer l'interception globale des mails et renseigner : (% style="letter-spacing: 0.0px;" %)**spring.mail.intercept.mailDigiposte**(%%) avec une adresse mail / liste
305
Matthieu Manginot 41.1 306 {{info}}
307 Une fois configuré, il faudra activer Digiposte avec la property **app.usingDigiposteDelivery : true**
308 {{/info}}
309
Matthieu Manginot 47.1 310 === Réaliser un test réel en production ===
Cédric Champmartin 2.1 311
Matthieu Manginot 48.1 312 Pour par exemple valider Digiposte en production, il est possible d'intercepter les mails pour un ou plusieurs étudiants d'un diplôme. (Intercepter = Remplacement du mail de l'étudiant par celui configuré)
Matthieu Manginot 41.1 313
Matthieu Manginot 46.1 314 {{info}}
Matthieu Manginot 47.1 315 Si l'interception globale est activée, elle **sera prioritaire** sur celle-ci
316 {{/info}}
317
318
Matthieu Manginot 46.1 319 Dans **application.yaml** sous **spring.mail, il faudra décommenter les éléments suivant pour activer l'interception :**
320
321 * **interceptEtudiants
322 **
323 ** **codDiplome :** A remplacer par le code diplôme à intercepter**
324 **
325 *** **"codEtudiant" :  **A remplacer par le code étudiant à intercepter
326
327 Exemple :
328
329 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
330 spring:
331 mail:
332 ...
333 interceptEtudiants:
334 ABCDEF:
335 "12345678": interceptMail@univ.fr
336 {{/code}}
337
338 Un message d'avertissement sera affiché dans l'interface pour le diplôme concerné :
339
340 [[image:attach:image2021-4-21_12-2-30.png||height="250"]]
341
Matthieu Manginot 40.1 342 ----
343
Matthieu Manginot 34.1 344 == (% style="letter-spacing: -0.006em;" %)Administration(%%) ==
Cédric Champmartin 2.1 345
Cédric Champmartin 9.1 346 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
347
Cédric Champmartin 8.1 348 === Gestion ===
349
350 \\
351
352 |=(((
353 Vue
354 )))|=(((
355 Utilisation
356 )))
357 |(((
358 (% class="content-wrapper" %)
359 (((
Matthieu Manginot 31.1 360 [[image:attach:image2021-2-23_10-42-24.png||height="400"]]
Cédric Champmartin 8.1 361 )))
362 )))|(((
363 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
364
365 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
366
367 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
368
369 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
370 )))
Matthieu Manginot 16.1 371
372 === Loggers ===
373
374 \\
375
376 |=(((
377 Vue
378 )))|=(((
379 Utilisation
380 )))
381 |(((
382 (% class="content-wrapper" %)
383 (((
Matthieu Manginot 31.1 384 [[image:attach:image2021-2-23_10-42-53.png||height="400"]]
Matthieu Manginot 16.1 385 )))
386 )))|(((
387 Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
388
Matthieu Manginot 31.1 389 Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
Matthieu Manginot 16.1 390 )))