Code source wiki de 01 - Documentation technique

Version 38.1 par Matthieu Manginot le 17/03/2021 - 11:31

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.
	10	* Le WAR pourra être pris en charge par un tomcat et servir les utilisateur•ices via l'URL configurée.
2.1	11
	12	\|=(((
	13	Technologie
	14	)))\|=(((
	15	Version
	16	)))
	17	\|(((
	18	JDK
	19	)))\|(((
	20	11+
	21	)))
	22	\|(% colspan="1" %)(((
	23	SpringBoot
	24	)))\|(% colspan="1" %)(((
	25	2.3
	26	)))
	27	\|(% colspan="1" %)(((
	28	Vaadin (Frontend)
	29	)))\|(% colspan="1" %)(((
	30	14
	31	)))
	32	\|(((
	33	Tomcat
	34	)))\|(((
	35	9+
	36	)))
	37	\|(% colspan="1" %)(((
	38	MariaDB
	39	)))\|(% colspan="1" %)(((
	40	14+
	41	)))
	42	\|(% colspan="1" %)(((
	43	Maven
	44	)))\|(% colspan="1" %)(((
	45	3.6+
	46	)))
	47	\|(% colspan="1" %)(((
	48	Connection Apogée
	49	)))\|(% colspan="1" %)(((
1.1	50	\\
2.1	51	)))
	52	\|(% colspan="1" %)(((
	53	Connection Apogée via WS
	54	)))\|(% colspan="1" %)(((
21.1	55	6.00.50
2.1	56	)))
	57	\|(% colspan="1" %)(((
	58	Connection LDAP
	59	)))\|(% colspan="1" %)(((
	60	\\
	61	)))
	62
	63	== Téléchargement des sources ==
	64
28.1	65	La dernière version des sources : [[hypercerts-1.0.4-SNAPSHOT.zip>>url:https://download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.4-SNAPSHOT.zip\|\|shape="rect"]]
2.1	66
	67	== Installation d'Hypercerts ==
	68
27.1	69	=== Initialisation / Mise à jour de la base ===
2.1	70
27.1	71	La base "//hypercerts//" MariaDB/MySQL s'initialise / se met à jour avec la commande Flyway suivante :
2.1	72
	73	{{code language="bash" theme="Eclipse"}}
	74	mvn -Dflyway.configFiles=flyway.properties flyway:migrate
	75	{{/code}}
	76
33.1	77	Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
2.1	78
	79	{{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
	80	# Flyway
	81	# ConfigFiles : https://flywaydb.org/documentation/configfiles
	82	# mvn -Dflyway.configFiles=xxx.properties flyway:migrate
	83	flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
	84	flyway.schemas=hypercerts
	85	flyway.user=XXX
	86	flyway.password=
	87	# Emplacement des fichiers sql de migration
	88	flyway.locations=classpath:db/migration
	89	# baselineOnMigrate
	90	flyway.baselineOnMigrate=false
	91	{{/code}}
	92
36.1	93	Au besoin, les fichiers sql de migration peuvent être trouvés sous src/main/resources/db/migration.
2.1	94
36.1	95	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	96
	97	=== Configuration de l'application ===
	98
	99	Créer et compléter un fichier application.yaml à la racine du projet sur le modèle de application-sample.yaml
	100
33.1	101	Des indications sont présentes dans le fichier pour aider à sa configuration ou ci-dessous.
2.1	102
33.1	103	=== Maven / Exécution de l'application ===
2.1	104
35.1	105	* Sous un IDE, exemple Eclipse//, avec fichier de configuration à la racine// :
33.1	106	** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
35.1	107	* Lancer l'application (hors d'un IDE),// avec fichier de configuration à la racine// :
32.1	108
33.1	109	{{code language="bash" theme="Eclipse"}}
	110	mvn spring-boot:run
	111	{{/code}}
32.1	112
33.1	113	* Lancer les tests :
32.1	114
33.1	115	{{code language="bash" theme="Eclipse"}}
	116	mvn verify
	117	{{/code}}
32.1	118
33.1	119	* Créer le package pour production :
	120
	121	{{code language="bash" theme="Eclipse"}}
	122	mvn clean package -Pproduction
	123	{{/code}}
	124
	125	* 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 :
	126
	127	{{code language="bash" theme="Eclipse"}}
	128	export JAVA_OPTS="$JAVA_OPTS -Dspring.config.location=$HOMEDIR/application.yaml"
	129	{{/code}}
	130
36.1	131	== (% style="letter-spacing: -0.006em;" %)Configuration(%%) ==
33.1	132
34.1	133	=== Property //app.production// ===
2.1	134
13.1	135	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	136
37.1	137	En étant à false, cette property autorise également la configuration de l'interception de tout les mails applicatifs.
2.1	138
	139	==== Envoi de mail ====
	140
	141	(% 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é :__
	142
	143	* d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/\|\|shape="rect"]]) en remplacement de votre smtp
13.1	144	* ou de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
	145	app.production** à //false//
	146	spring.mail.intercept.active** à //true//
2.1	147	et spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
	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
34.1	151	=== WebServices Apogée ===
2.1	152
	153	Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
	154
36.1	155	Les properties différent du classique fichier de configuration configUrlServices.properties de l'AMUE.
2.1	156
36.1	157	Des headers peuvent être ajoutés en paramètre de chaque WebServices.
2.1	158
	159	Exemple :
	160
	161	{{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
	162	ws:
	163	apogee:
	164	administratif:
	165	url: https://api.univ.fr/apo/amue_apo_administratif
	166	headers:
	167	# header1: value1
	168	# header2: value2
	169	username: xxxx
	170	password: xxxx
	171	{{/code}}
	172
35.1	173	=== Customisation des templates de mail ===
	174
37.1	175	Les properties suivantes servent à indiquer les templates personnalisés :
35.1	176
37.1	177	* spring.mail.templateName.attestation : pour le mail à destination de l'étudiant contenant l'attestation
	178	* spring.mail.templateName.creationDigiposte : pour le mail à destination de l'étudiant envoyé après la création du coffre Digiposte
	179	* spring.mail.templateName.creationCampagne : pour le mail d'une nouvelle campagne (à destination du gestionnaire qui a lancé la campagne)
	180	* spring.mail.templateName.reportCampagne : pour le mail de rapport de campagne (à destination du gestionnaire qui a lancé la campagne)
	181
	182	❓ Par défaut, les valeurs sont vides et les templates par défaut de l'application sont utilisés
	183
38.1	184	Pour customiser un template :
	185
	186	* Copier et renommer un template HTML présent sous src/main/resources/templates
	187	* Par exemple pour le mail d'attestation :
	188	Renommer mail-attestation.html en mail-attestation-custom.html**
	189	** Adapter le template
	190	Dans la config, saisir spring.mail.templateName.attestation : mail-attestation-custom.html**
	191
2.1	192	=== Customisation des services ===
	193
	194	Plusieurs services sont personnalisables en fonction de votre environnement.
	195
36.1	196	Sous fr.univlorraine.hypercerts.apogee.service.customs :
2.1	197
36.1	198	* **ApogeeUtilisateurServiceCustomExample//
	199	//**
25.1	200	** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
36.1	201	* **ApogeeBlocageServiceCustomExample//
	202	//**
2.1	203	** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
36.1	204	* **ApogeeComposanteServiceCustomExample//
	205	//**
2.1	206	** Personnalisation de la récupération :
15.1	207	*** de toutes les composantes
	208	**** → utilisé pour donner les droits sur toutes les composantes aux super admins
25.1	209	*** des composantes pour un utilisateur à partir de l'uid Apogée
	210	*** du nombre de composantes pour un utilisateur à partir de l'uid Apogée
36.1	211	* ApogeeUidServiceCustomExample\\
25.1	212	** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
2.1	213
15.1	214	(% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
2.1	215
	216	1. Copier la classe en la renommant
	217	1. Implémenter la ou les méthodes
	218	11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
	219	1. (((
	220	Dé-commenter les 2 annotations :1. (((
36.1	221	@Service → Pour que Spring implémente le Service au démarrage
2.1	222	)))
	223	1. (((
36.1	224	et @OverrideXXX → Pour que l'implémentation surcharge le service par défaut
2.1	225	)))
	226	)))
	227	1. Au démarrage de l'application
	228	11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
25.1	229	1. Sans IDE, penser à ajouter les imports suivant :
	230	11. import org.springframework.stereotype.Service;
37.1	231	11. import fr.univlorraine.hypercerts.apogee.services.annotations.OverrideXXX;
15.1	232	\\
2.1	233
15.1	234	{{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
2.1	235	/**
26.1	236	* Override default ApogeeUtilisateurService implementation.
2.1	237	* >> README
26.1	238	* 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	239	*
	240	* @author Matthieu Manginot
	241	*/
	242	@NoArgsConstructor
	243	@Slf4j
26.1	244	// @Service
	245	// @OverrideApogeeUtilisateurService
	246	public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
2.1	247
	248	@PersistenceContext(unitName = "apogeeEntityManagerFactory")
	249	private EntityManager entityManagerApogee;
	250
	251	@PostConstruct
	252	public void init() {
26.1	253	log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
2.1	254	}
	255
	256	/**
26.1	257	* @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
2.1	258	*/
	259	@Override
26.1	260	public String getMail(final String uidApogee) {
	261	/* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
	262	return null;
2.1	263	}
	264	}
	265	{{/code}}
	266
15.1	267	=== Paramétrage de Digiposte ===
2.1	268
3.1	269	//Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
2.1	270
15.1	271	//Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
	272
34.1	273	== (% style="letter-spacing: -0.006em;" %)Administration(%%) ==
2.1	274
9.1	275	Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
	276
8.1	277	=== Gestion ===
	278
	279	\\
	280
	281	\|=(((
	282	Vue
	283	)))\|=(((
	284	Utilisation
	285	)))
	286	\|(((
	287	(% class="content-wrapper" %)
	288	(((
31.1	289	[[image:attach:image2021-2-23_10-42-24.png\|\|height="400"]]
8.1	290	)))
	291	)))\|(((
	292	Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
	293
	294	Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
	295
	296	On peut aussi utiliser des boutons pour lancer plus finement des tâches.
	297
	298	À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
	299	)))
16.1	300
	301	=== Loggers ===
	302
	303	\\
	304
	305	\|=(((
	306	Vue
	307	)))\|=(((
	308	Utilisation
	309	)))
	310	\|(((
	311	(% class="content-wrapper" %)
	312	(((
31.1	313	[[image:attach:image2021-2-23_10-42-53.png\|\|height="400"]]
16.1	314	)))
	315	)))\|(((
	316	Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
	317
31.1	318	Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
16.1	319	)))

Code source wiki de 01 - Documentation technique

Arborescence des pages

Pour vous aider