Code source wiki de Accueil Hypercerts

Version 49.1 par Cédric Champmartin le 23/07/2020 - 13:55
Afficher les derniers auteurs
1
2
3 {{toc/}}
4
5 Vous cherchez à délivrer aux étudiants de votre université des attestations de réussite dématérialisées ? Hypercerts vous permettera de générer et envoyer des attestations officielles, numériques, et infalsifiables de façon automatique.
6
7 Ces dernières pourront être envoyées par mail, déposées dans le nuage, et même être certifiées authentiques grâce à une blockchain dédiée.
8
9 Une fois l'application connectée à Apogée et au LDAP, les gestionnaires de scolarité pourront demander la génération et l'envoi des attestations de réussite en un clic.
10
11 {{info}}
12 La version 1.0.x est une première version limitée à l'envoi des attestations par email. Bien que le cœur de l'application soit fonctionnel, les dépôts de documents dans les coffres digisposte et la certification cryptographique sont en cours de développement actif.
13 {{/info}}
14
15 == ==
16
17 {{confluence_children/}}
18
19 == Prérequis ==
20
21 Hypercerts est une application Java qui se connecte à Apogée et au LDAP. Elle requiert l'utilisation d'une base MariaDB pour son fonctionnement interne. Elle se déploie sur des serveurs comme une application SpringBoot classique. Le WAR pourra être pris en charge par un tomcat et servir les utilisateur•ices via l'URL configurée.
22
23 (% class="wrapped" %)
24 |=(((
25 Technologie
26 )))|=(((
27 Version
28 )))
29 |(((
30 JDK
31 )))|(((
32 11+
33 )))
34 |(% colspan="1" %)(((
35 SpringBoot
36 )))|(% colspan="1" %)(((
37 2.3
38 )))
39 |(% colspan="1" %)(((
40 Vaadin (Frontend)
41 )))|(% colspan="1" %)(((
42 14
43 )))
44 |(((
45 Tomcat
46 )))|(((
47 9+
48 )))
49 |(% colspan="1" %)(((
50 MariaDB
51 )))|(% colspan="1" %)(((
52 14+
53 )))
54 |(% colspan="1" %)(((
55 Maven
56 )))|(% colspan="1" %)(((
57 3.6+
58 )))
59 |(% colspan="1" %)(((
60 Connection Apogée
61 )))|(% colspan="1" %)(((
62 \\
63 )))
64 |(% colspan="1" %)(((
65 Connection Apogée via WS
66 )))|(% colspan="1" %)(((
67 \\
68 )))
69 |(% colspan="1" %)(((
70 Connection LDAP
71 )))|(% colspan="1" %)(((
72 \\
73 )))
74 |(% colspan="1" %)(((
75 Docker (optionnel)
76 )))|(% colspan="1" %)(((
77 docker-compose 3
78 )))
79
80 == Téléchargement des sources ==
81
82 Les sources de l'application peuvent être téléchargées à [[cet endroit>>url:ftp://dufour18@download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.2-SNAPSHOT.zip||shape="rect"]].
83
84 == Installation d'Hypercerts ==
85
86 === **Initialisation de la base** ===
87
88 La base de données MariaDB/MySQL s'initialise avec la commande Flyway suivante :
89
90 {{code language="bash" theme="Eclipse"}}
91 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
92 {{/code}}
93
94 Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
95
96 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
97 # Flyway
98 # ConfigFiles : https://flywaydb.org/documentation/configfiles
99 # mvn -Dflyway.configFiles=xxx.properties flyway:migrate
100 flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
101 flyway.schemas=hypercerts
102 flyway.user=XXX
103 flyway.password=
104 # Emplacement des fichiers sql de migration
105 flyway.locations=classpath:db/migration
106 # baselineOnMigrate
107 flyway.baselineOnMigrate=false
108 {{/code}}
109
110 Au besoin, les fichiers sql de migration peuvent être trouvés sous //src/main/resources/db/migration//.
111
112 Pour remettre à zéro la base, lancer le script //src/main/resources/db/reset/reset.sql //puis exécuter à nouveau Flyway//.//
113
114 === Configuration de l'application ===
115
116 Créer et compléter un fichier **application.yaml** à la racine du projet sur le modèle de **application-sample.yaml**
117
118 Des indications sont présentes dans le fichier pour aider à sa configuration.
119
120 === **Éléments de configuration importants** ===
121
122 ==== Property (% style="letter-spacing: -0.003em;" %)//app.production//(%%) ====
123
124 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.
125
126 En étant à false, cette property autorise également l'interception de tous les mails applicatifs.
127
128 ==== **Envoi de mail** ====
129
130 (% 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é :__
131
132 * d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/||shape="rect"]]) en remplacement de votre smtp
133 * ou de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
134 ** **app.production** à false
135 ** **spring.mail.intercept.active** à true
136 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
137
138 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 sont en copie de cette property. Elle peut être laissée vide.
139
140 ==== WebServices Apogée ====
141
142 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
143
144 Les properties différent du classique configUrlServices.properties de l'AMUE.
145
146 Des headers peuvent être ajoutés en paramètre de chaque WebService.
147
148 Exemple :
149
150 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
151 ws:
152 apogee:
153 administratif:
154 url: https://api.univ.fr/apo/amue_apo_administratif
155 headers:
156 # header1: value1
157 # header2: value2
158 username: xxxx
159 password: xxxx
160 {{/code}}
161
162 === Configurer et lancer le projet dans Eclipse ===
163
164 * Importer le projet Maven dans eclipse.
165 * Lorsque la configuration est terminée, démarrer l'application en faisant un clic droit sur {{code language="none"}}fr.univlorraine.hypercerts.Application.java{{/code}} et en choisissant 'Run As / Java Application'.
166
167 === Customisation des services ===
168
169 Plusieurs services sont personnalisables en fonction de votre environnement.
170
171 Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
172
173 * ApogeeUserServiceCustomExample
174 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid LDAP
175 * BlocageServiceCustomExample
176 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
177 * ComposanteServiceCustomExample
178 ** Personnalisation de la récupération :
179 *** de toutes les composantes
180 *** des composantes pour un utilisateur à partir de l'uid LDAP
181 *** du nombre de composantes pour un utilisateur à partir de l'uid LDAP
182
183 Pour personnaliser un de ces services :
184
185 1. Copier la classe en la renommant
186 1. Implémenter la ou les méthodes
187 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
188 1. (((
189 Dé-commenter les 2 annotations :1. (((
190 @Service
191 )))
192 1. (((
193 et @Override~*~*
194 )))
195 )))
196 1. Au démarrage de l'application
197 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
198
199 Exemple :
200
201 {{code language="java" theme="Eclipse" linenumbers="true" collapse="true"}}
202 /**
203 * Override default ApogeeUserService implementation.
204 * >> README
205 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUserService pour que l'implémentation soit utilisée.
206 *
207 * @author Matthieu Manginot
208 */
209 @NoArgsConstructor
210 @Slf4j
211 @Service
212 @OverrideApogeeUserService
213 public class ApogeeUserServicePERSO implements IApogeeUserService {
214
215 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
216 private EntityManager entityManagerApogee;
217
218 @PostConstruct
219 public void init() {
220 log.info("Overriding {} for IApogeeUserService implementation", getClass().getCanonicalName());
221 }
222
223 /**
224 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUserService#getEmail(java.lang.String)
225 */
226 @Override
227 public String getEmail(final String uidLdap) {
228 /* Implémentation personnalisée de getEmail. entityManagerApogee.createNativeQuery... */
229 return "mail@univ.fr";
230 }
231 }
232 {{/code}}
233
234 ===
235 Customisation de Digiposte ===
236
237 //Documentation à venir.//
238
239 === Tâches Maven ===
240
241 * Lancer l'application (hors d'un IDE) :
242
243 {{code language="bash" theme="Eclipse"}}
244 mvn spring-boot:run
245 {{/code}}
246
247 * Lancer les tests :
248
249 {{code language="bash" theme="Eclipse"}}
250 mvn verify
251 {{/code}}
252
253 * Créer le package pour production :
254
255 {{code language="bash" theme="Eclipse"}}
256 mvn clean package -Pproduction
257 {{/code}}
258
259 === Makefile ===
260
261 Un Makefile est également disponible. A la racine, utilisez `make help` pour obtenir les commandes disponibles.
262
263 == Tests unitaires ==
264
265 Pour s'assurez que les résultats d'admission de vos étudiants soient bien correctes, et afin d'éviter les faux positifs (donc envoyer une attestation de réussite à un•e étudiant•e non reçu•e aux examens), vous pouvez ajouter vos jeux de données.
266
267 Les tests utilisent 3 classes:
268
269 (% style="list-style-type: square;" %)
270 * ResultatsTests.java
271 * ResultatsTestCase.java
272 * ResultatsServiceTest.java
273
274 ResultatTests.java énumère tous les tests. Il utilise l'objet ResultatTestCase dans lequel on précise:
275
276 (% style="list-style-type: square;" %)
277 * Le codEtu
278 * L'année
279 * Le diplôme
280 * La VDI
281 * Le résultat attendu (le test réussi si c'est ce résultat qui est trouvé)
282
283 ResultatServiceTest.java est responsable du lancement des tests JUnit
284
285 Ainsi, pour créer vos tests, ajoutez votre jeu de données dans ResultatTests, avec des résultats d'admissions réputés corrects et utilisez ResultatServiceTest pour tester les cas consécutivement.
286
287 == Utilisation d'Hypercerts ==
288
289 (% class="relative-table wrapped" style="width: 100.0%;" %)
290 |=(((
291 Vue
292 )))|=(((
293 Utilisation
294 )))
295 |(((
296 (% class="content-wrapper" %)
297 (((
298 [[image:attach:1-Accueil.png||height="400"]]
299 )))
300 )))|(((
301 (% class="content-wrapper" %)
302 (((
303 En tant que gestionnaire de scolarité ou super admin, rendez vous sur l'application.
304
305 Une fois le CAS passé, vous atteignez la page d'accueil de l'application. Vous y retrouvez les composantes dans lesquelles vous pourrez faire des demandes de génération en envoi d'attestations dématérialisées. Pour les gestionnaires, celles-ci correspondent à vos droits Apogée. Les super admins ont eux accès à toutes les composantes.
306
307 Dans le panneau de gauche, vous retrouvez une série d'onglets. Ceux-ci sont disposés de haut en bas, dans l'ordre de leur utilisation.
308 )))
309 )))
310 |(((
311 (% class="content-wrapper" %)
312 (((
313 [[image:attach:2-Génération.png||height="400"]]
314 )))
315 )))|(((
316 Pour lancer la génération d'attestations de réussite pour un diplôme (créer une campagne de dématérialisation) choisissez:
317
318 (% style="list-style-type: square;" %)
319 * L'année académique
320 * La composante
321 * Le diplôme (les résultats proposés correspondent à la composante sélectionnée)
322
323 L'application retrouve les promotions d'étudiant.es et récapitule les informations avant le lancement des demandes.
324
325 Vous pouvez utiliser le bouton visualiser un specimen d'attestation pour valider visuellement le rendu des attestations qui vont être générées.
326
327 Veillez à ce que le libelle du diplôme soit bien celui que vous attendez.
328
329 \\
330
331 * //Le bouton avec les flèches en rond permet de forcer une nouvelle recherche//
332 * //Le bouton gomme permet d'effacer les paramètres//
333 )))
334 |(((
335 (% class="content-wrapper" %)
336 (((
337 **Avant la fin du traitement automatique**
338
339 [[image:attach:3-diplomes.png||height="400"]]
340 )))
341 )))|(% rowspan="2" %)(((
342 Une fois vos demandes faites, vous retrouvez leur avancement dans la vue "Diplômes"
343
344 Après que le traitement des demandes soit fait, les diplômes passent dans la section 'Terminés'
345
346 On y retrouve des informations relatives à la génération et distribution des attestations.
347
348 Le même rapport a été envoyé par email au gestionnaire qui à fait la demande.
349 )))
350 |(((
351 (% class="content-wrapper" %)
352 (((
353 **Après le traitement automatique**
354
355 [[image:attach:3-2.png||height="400"]]
356 )))
357 )))
358 |(% colspan="1" %)(((
359 (% class="content-wrapper" %)
360 (((
361 === [[image:attach:4-etudiants.png||height="400"]] ===
362 )))
363 )))|(% colspan="1" %)(((
364 Si on cherche à vérifier comment s'est déroulée la génération et distribution d'une attestation pour un•e étudiant•e, on peut utiliser la vue "Étudiants".
365
366 \\
367
368 On peut utiliser le codEtu ou recherche par nom / prénom.
369
370 \\
371
372 On retrouve toutes les années pour lesquelles l'un•e étudiant•e a été traitée. Pour chaque année sont précisés les diplômes, et pour chaque diplôme on retrouve le rapport des étapes dans l'ordre chronologique.
373
374 Si une erreur est survenue, la raison sera précisée ici.
375
376 \\
377
378 Il est aussi possible de télécharger l'attestation avec le bouton "Télécharger l'attestation"
379 )))
380
381 == Administration ==
382
383 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
384
385 [[image:attach:image2020-7-23_12-41-56.png||align="center" height="400"]]
386
387 === Connexions ===
388
389 \\
390
391 (% class="wrapped" %)
392 |=(((
393 Vue
394 )))|=(((
395 Utilisation
396 )))
397 |(% colspan="1" %)(((
398 (% class="content-wrapper" %)
399 (((
400 [[image:attach:image2020-7-23_12-45-23.png||height="400"]]
401 )))
402 )))|(% colspan="1" %)(((
403 Cette vue donne accès à la liste des utilisateurs connectés, leur IP, ainsi que la page qu'ils consultent.
404
405 Un superadmin peut aussi demander à prendre le rôle d'un autre utilisateur en saisissant sont identifiant LDAP.
406
407 Pour retrouver son profil de super admin, cliquer sur l'avatar en haut à droite, puis cliquer sur "Rétablir utilisateur"
408 )))
409
410 \\
411
412 === Gestion ===
413
414 \\
415
416 (% class="wrapped" %)
417 |=(((
418 Vue
419 )))|=(((
420 Utilisation
421 )))
422 |(((
423 (% class="content-wrapper" %)
424 (((
425 [[image:attach:image2020-7-23_12-51-28.png||height="400"]]
426 )))
427 )))|(((
428 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
429
430 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
431
432 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
433
434 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
435 )))
436
437 \\
438
439 \\
440
441 {{section}}
442 {{column width="60%"}}
443 {{recently-updated/}}
444 {{/column}}
445
446 {{column width="5%"}}
447 \\
448 {{/column}}
449
450 {{column width="35%"}}
451 ====== Navigate space ======
452
453 {{locationSearch reference="WebHome"/}}
454
455 {{pagetree/}}
456 {{/column}}
457 {{/section}}
458
459 {{code language="java" theme="Eclipse" linenumbers="true" collapse="true"}}
460 ws:
461 apogee:
462 administratif:
463 url: https://api.univ.fr/apo/amue_apo_administratif
464 headers:
465 # header1: value1
466 # header2: value2
467 username: xxxx
468 password: xxxx
469 {{/code}}