Code source wiki de 01 - Documentation technique

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