Code source wiki de Accueil Hypercerts

Version 48.1 par Cédric Champmartin le 23/07/2020 - 13:45
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ésentes dans le fichier pour aider à sa configuration.
115
116 === **Éléments de configuration importants** ===
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 tous 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 tous 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ée 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émenter 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. Une 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 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.
282
283 == Utilisation d'Hypercerts ==
284
285 (% class="relative-table wrapped" style="width: 100.0%;" %)
286 |=(((
287 Vue
288 )))|=(((
289 Utilisation
290 )))
291 |(((
292 (% class="content-wrapper" %)
293 (((
294 [[image:attach:1-Accueil.png||height="400"]]
295 )))
296 )))|(((
297 (% class="content-wrapper" %)
298 (((
299 En tant que gestionnaire de scolarité ou super admin, rendez vous sur l'application.
300
301 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.
302
303 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.
304 )))
305 )))
306 |(((
307 (% class="content-wrapper" %)
308 (((
309 [[image:attach:2-Génération.png||height="400"]]
310 )))
311 )))|(((
312 Pour lancer la génération d'attestations de réussite pour un diplôme (créer une campagne de dématérialisation) choisissez:
313
314 (% style="list-style-type: square;" %)
315 * L'année académique
316 * La composante
317 * Le diplôme (les résultats proposés correspondent à la composante sélectionnée)
318
319 L'application retrouve les promotions d'étudiant.es et récapitule les informations avant le lancement des demandes.
320
321 Vous pouvez utiliser le bouton visualiser un specimen d'attestation pour valider visuellement le rendu des attestations qui vont être générées.
322
323 Veillez à ce que le libelle du diplôme soit bien celui que vous attendez.
324
325 \\
326
327 * //Le bouton avec les flèches en rond permet de forcer une nouvelle recherche//
328 * //Le bouton gomme permet d'effacer les paramètres//
329 )))
330 |(((
331 (% class="content-wrapper" %)
332 (((
333 **Avant la fin du traitement automatique**
334
335 [[image:attach:3-diplomes.png||height="400"]]
336 )))
337 )))|(% rowspan="2" %)(((
338 Une fois vos demandes faites, vous retrouvez leur avancement dans la vue "Diplômes"
339
340 Après que le traitement des demandes soit fait, les diplômes passent dans la section 'Terminés'
341
342 On y retrouve des informations relatives à la génération et distribution des attestations.
343
344 Le même rapport a été envoyé par email au gestionnaire qui à fait la demande.
345 )))
346 |(((
347 (% class="content-wrapper" %)
348 (((
349 **Après le traitement automatique**
350
351 [[image:attach:3-2.png||height="400"]]
352 )))
353 )))
354 |(% colspan="1" %)(((
355 (% class="content-wrapper" %)
356 (((
357 === [[image:attach:4-etudiants.png||height="400"]] ===
358 )))
359 )))|(% colspan="1" %)(((
360 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".
361
362 \\
363
364 On peut utiliser le codEtu ou recherche par nom / prénom.
365
366 \\
367
368 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.
369
370 Si une erreur est survenue, la raison sera précisée ici.
371
372 \\
373
374 Il est aussi possible de télécharger l'attestation avec le bouton "Télécharger l'attestation"
375 )))
376
377 == Administration ==
378
379 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
380
381 [[image:attach:image2020-7-23_12-41-56.png||align="center" height="400"]]
382
383 === Connexions ===
384
385 \\
386
387 (% class="wrapped" %)
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 (% class="wrapped" %)
413 |=(((
414 Vue
415 )))|=(((
416 Utilisation
417 )))
418 |(((
419 (% class="content-wrapper" %)
420 (((
421 [[image:attach:image2020-7-23_12-51-28.png||height="400"]]
422 )))
423 )))|(((
424 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
425
426 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
427
428 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
429
430 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
431 )))
432
433 \\
434
435 \\
436
437 {{section}}
438 {{column width="60%"}}
439 {{recently-updated/}}
440 {{/column}}
441
442 {{column width="5%"}}
443 \\
444 {{/column}}
445
446 {{column width="35%"}}
447 ====== Navigate space ======
448
449 {{locationSearch reference="WebHome"/}}
450
451 {{pagetree/}}
452 {{/column}}
453 {{/section}}
454
455 {{code language="java" theme="Eclipse" linenumbers="true" collapse="true"}}
456 ws:
457 apogee:
458 administratif:
459 url: https://api.univ.fr/apo/amue_apo_administratif
460 headers:
461 # header1: value1
462 # header2: value2
463 username: xxxx
464 password: xxxx
465 {{/code}}