Code source wiki de 01 - Documentation technique

Version 64.5 par Matthieu Manginot le 11/07/2024 - 08:50

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

Code source wiki de 01 - Documentation technique

Arborescence des pages

Pour vous aider