Code source wiki de Documentation technique

Version 17.1 par Cédric Champmartin le 23/07/2020 - 15:59

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" %)(((
	55	\\
	56	)))
	57	\|(% colspan="1" %)(((
	58	Connection LDAP
	59	)))\|(% colspan="1" %)(((
	60	\\
	61	)))
	62	\|(% colspan="1" %)(((
	63	Docker (optionnel)
	64	)))\|(% colspan="1" %)(((
	65	docker-compose 3
	66	)))
	67
	68	== Téléchargement des sources ==
	69
17.1	70	Les sources de l'application peuvent être téléchargées à [[cet endroit>>url:https://download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.2-SNAPSHOT.zip\|\|shape="rect"]].
2.1	71
	72	== Installation d'Hypercerts ==
	73
	74	=== Initialisation de la base ===
	75
11.1	76	Après avoir créé une base de données "//hypercerts//", la base de données MariaDB/MySQL s'initialise avec la commande Flyway suivante :
2.1	77
	78	{{code language="bash" theme="Eclipse"}}
	79	mvn -Dflyway.configFiles=flyway.properties flyway:migrate
	80	{{/code}}
	81
	82	Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
	83
	84	{{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
	85	# Flyway
	86	# ConfigFiles : https://flywaydb.org/documentation/configfiles
	87	# mvn -Dflyway.configFiles=xxx.properties flyway:migrate
	88	flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
	89	flyway.schemas=hypercerts
	90	flyway.user=XXX
	91	flyway.password=
	92	# Emplacement des fichiers sql de migration
	93	flyway.locations=classpath:db/migration
	94	# baselineOnMigrate
	95	flyway.baselineOnMigrate=false
	96	{{/code}}
	97
	98	Au besoin, les fichiers sql de migration peuvent être trouvés sous //src/main/resources/db/migration//.
	99
12.1	100	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	101
	102	=== Configuration de l'application ===
	103
	104	Créer et compléter un fichier application.yaml à la racine du projet sur le modèle de application-sample.yaml
	105
	106	Des indications sont présentes dans le fichier pour aider à sa configuration.
	107
	108	=== Éléments de configuration importants ===
	109
	110	==== Property //app.production// ====
	111
13.1	112	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	113
13.1	114	En étant à //false//, cette //property// autorise également la configuration de l'interception de tout les mails applicatifs.
2.1	115
	116	==== Envoi de mail ====
	117
	118	(% 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é :__
	119
	120	* d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/\|\|shape="rect"]]) en remplacement de votre smtp
13.1	121	* ou de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
	122	app.production** à //false//
	123	spring.mail.intercept.active** à //true//
2.1	124	et spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
	125
13.1	126	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	127
	128	==== WebServices Apogée ====
	129
	130	Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
	131
14.1	132	Les //properties// différent du classique fichier de configuration //configUrlServices.properties// de l'AMUE.
2.1	133
14.1	134	Des //headers// peuvent être ajoutés en paramètre de chaque WebServices.
2.1	135
	136	Exemple :
	137
	138	{{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
	139	ws:
	140	apogee:
	141	administratif:
	142	url: https://api.univ.fr/apo/amue_apo_administratif
	143	headers:
	144	# header1: value1
	145	# header2: value2
	146	username: xxxx
	147	password: xxxx
	148	{{/code}}
	149
	150	=== Configurer et lancer le projet dans Eclipse ===
	151
14.1	152	* Importer le projet Maven dans Eclipse.
	153	* Lorsque la configuration est terminée, démarrer l'application en faisant un clic droit sur la classe {{code language="none"}}fr.univlorraine.hypercerts.Application.java{{/code}} et en choisissant 'Run As / Java Application'.
2.1	154
	155	=== Customisation des services ===
	156
	157	Plusieurs services sont personnalisables en fonction de votre environnement.
	158
	159	Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
	160
15.1	161	* //ApogeeUserServiceCustomExample//
2.1	162	** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid LDAP
15.1	163	* //BlocageServiceCustomExample//
2.1	164	** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
15.1	165	* //ComposanteServiceCustomExample//
2.1	166	** Personnalisation de la récupération :
15.1	167	*** de toutes les composantes
	168	**** → utilisé pour donner les droits sur toutes les composantes aux super admins
2.1	169	*** des composantes pour un utilisateur à partir de l'uid LDAP
	170	*** du nombre de composantes pour un utilisateur à partir de l'uid LDAP
	171
15.1	172	(% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
2.1	173
	174	1. Copier la classe en la renommant
	175	1. Implémenter la ou les méthodes
	176	11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
	177	1. (((
	178	Dé-commenter les 2 annotations :1. (((
5.1	179	@Service → Pour que Spring implémente le Service au démarrage
2.1	180	)))
	181	1. (((
5.1	182	et @Override~~ → Pour que l'implémentation surcharge le service par défaut
2.1	183	)))
	184	)))
	185	1. Au démarrage de l'application
	186	11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
15.1	187	\\
2.1	188
15.1	189	{{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
2.1	190	/**
	191	* Override default ApogeeUserService implementation.
	192	* >> README
	193	* Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUserService pour que l'implémentation soit utilisée.
	194	*
	195	* @author Matthieu Manginot
	196	*/
	197	@NoArgsConstructor
	198	@Slf4j
	199	@Service
	200	@OverrideApogeeUserService
	201	public class ApogeeUserServicePERSO implements IApogeeUserService {
	202
	203	@PersistenceContext(unitName = "apogeeEntityManagerFactory")
	204	private EntityManager entityManagerApogee;
	205
	206	@PostConstruct
	207	public void init() {
	208	log.info("Overriding {} for IApogeeUserService implementation", getClass().getCanonicalName());
	209	}
	210
	211	/**
	212	* @see fr.univlorraine.hypercerts.apogee.services.IApogeeUserService#getEmail(java.lang.String)
	213	*/
	214	@Override
	215	public String getEmail(final String uidLdap) {
	216	/* Implémentation personnalisée de getEmail. entityManagerApogee.createNativeQuery... */
	217	return "mail@univ.fr";
	218	}
	219	}
	220	{{/code}}
	221
15.1	222	=== Paramétrage de Digiposte ===
2.1	223
3.1	224	//Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
2.1	225
15.1	226	//Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
	227
2.1	228	=== Tâches Maven ===
	229
	230	* Lancer l'application (hors d'un IDE) :
	231
	232	{{code language="bash" theme="Eclipse"}}
	233	mvn spring-boot:run
	234	{{/code}}
	235
	236	* Lancer les tests :
	237
	238	{{code language="bash" theme="Eclipse"}}
	239	mvn verify
	240	{{/code}}
	241
	242	* Créer le package pour production :
	243
	244	{{code language="bash" theme="Eclipse"}}
	245	mvn clean package -Pproduction
	246	{{/code}}
	247
	248	=== Makefile ===
	249
	250	Un Makefile est également disponible. A la racine, utilisez `make help` pour obtenir les commandes disponibles.
8.1	251
9.1	252	== Administration ==
	253
	254	Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
	255
	256	[[image:attach:image2020-7-23_12-41-56.png\|\|align="center" height="400"]]
	257
8.1	258	=== Gestion ===
	259
	260	\\
	261
	262	\|=(((
	263	Vue
	264	)))\|=(((
	265	Utilisation
	266	)))
	267	\|(((
	268	(% class="content-wrapper" %)
	269	(((
	270	[[image:attach:image2020-7-23_12-51-28.png\|\|height="400"]]
	271	)))
	272	)))\|(((
	273	Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
	274
	275	Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
	276
	277	On peut aussi utiliser des boutons pour lancer plus finement des tâches.
	278
	279	À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
	280	)))
16.1	281
	282	=== Loggers ===
	283
	284	\\
	285
	286	\|=(((
	287	Vue
	288	)))\|=(((
	289	Utilisation
	290	)))
	291	\|(((
	292	(% class="content-wrapper" %)
	293	(((
	294	[[image:attach:image2020-7-23_15-56-58.png\|\|height="250"]]
	295	)))
	296	)))\|(((
	297	Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
	298
	299	Utile pour afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
	300	)))

Code source wiki de Documentation technique

Arborescence des pages

Pour vous aider