Aller au contenu

Code source wiki de 01 - Documentation technique

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