Code source wiki de 01 - Documentation technique

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

Code source wiki de 01 - Documentation technique

Arborescence des pages

Pour vous aider