Code source wiki de 01 - Documentation technique

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