Code source wiki de 01 - Documentation technique

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