Code source wiki de 01 - Documentation technique

Modifié par Matthieu Manginot le 29/04/2025 - 10:52

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

Code source wiki de 01 - Documentation technique

Arborescence des pages

Pour vous aider