Code source wiki de Accueil Hypercerts

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