Code source wiki de 01 - Documentation technique

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