Code source wiki de Accueil Hypercerts

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