Aller au contenu

Code source wiki de 01 - Documentation technique

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