Code source wiki de 01 - Documentation technique

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