Aller au contenu

Code source wiki de 01 - Documentation technique

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