Code source wiki de 01 - Documentation technique

Version 59.1 par Matthieu Manginot le 13/04/2022 - 11:58

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

Code source wiki de 01 - Documentation technique

Arborescence des pages

Pour vous aider