Aller au contenu

Code source wiki de 01 - Documentation technique

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