Code source wiki de 01 - Documentation technique

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