Code source wiki de 01 - Documentation technique

Version 68.1 par Matthieu Manginot le 14/04/2025 - 15:04

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

Code source wiki de 01 - Documentation technique

Arborescence des pages

Pour vous aider