Aller au contenu

Code source wiki de 01 - Documentation technique

Version 31.1 par Matthieu Manginot le 23/02/2021 - 10:43
Afficher les derniers auteurs
1
2
3 {{toc/}}
4
5 == Prérequis ==
6
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.
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" %)(((
50 \\
51 )))
52 |(% colspan="1" %)(((
53 Connection Apogée via WS
54 )))|(% colspan="1" %)(((
55 6.00.50
56 )))
57 |(% colspan="1" %)(((
58 Connection LDAP
59 )))|(% colspan="1" %)(((
60 \\
61 )))
62
63 == Téléchargement des sources ==
64
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"]]
66
67 == Installation d'Hypercerts ==
68
69 === **Initialisation / Mise à jour de la base** ===
70
71 La base "//hypercerts//" MariaDB/MySQL s'initialise / se met à jour avec la commande Flyway suivante :
72
73 {{code language="bash" theme="Eclipse"}}
74 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
75 {{/code}}
76
77 Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
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
93 Au besoin, les fichiers sql de migration peuvent être trouvés sous //src/main/resources/db/migration//.
94
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//.//
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
101 Des indications sont présentes dans le fichier pour aider à sa configuration.
102
103 === **Éléments de configuration importants** ===
104
105 ==== Property //app.production// ====
106
107 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.
108
109 En étant à //false//, cette //property// autorise également la configuration de l'interception de tout les mails applicatifs.
110
111 ==== **Envoi de mail** ====
112
113 (% 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é :__
114
115 * d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/||shape="rect"]]) en remplacement de votre smtp
116 * **ou** de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
117 ** **app.production** à //false//
118 ** **spring.mail.intercept.active** à //true//
119 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
120
121 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.
122
123 ==== WebServices Apogée ====
124
125 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
126
127 Les //properties// différent du classique fichier de configuration //configUrlServices.properties// de l'AMUE.
128
129 Des //headers// peuvent être ajoutés en paramètre de chaque WebServices.
130
131 Exemple :
132
133 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
134 ws:
135 apogee:
136 administratif:
137 url: https://api.univ.fr/apo/amue_apo_administratif
138 headers:
139 # header1: value1
140 # header2: value2
141 username: xxxx
142 password: xxxx
143 {{/code}}
144
145 === Configurer et lancer le projet dans Eclipse ===
146
147 * Importer le projet Maven dans Eclipse.
148 * 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'.
149
150 === Customisation des services ===
151
152 Plusieurs services sont personnalisables en fonction de votre environnement.
153
154 Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
155
156 * //ApogeeUtilisateurServiceCustomExample
157 //
158 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
159 * //ApogeeBlocageServiceCustomExample
160 //
161 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
162 * //ApogeeComposanteServiceCustomExample
163 //
164 ** Personnalisation de la récupération :
165 *** de toutes les composantes 
166 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
167 *** des composantes pour un utilisateur à partir de l'uid Apogée
168 *** du nombre de composantes pour un utilisateur à partir de l'uid Apogée
169 * ApogeeUidServiceCustomExample\\
170 ** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
171
172 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
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. (((
179 @Service → Pour que Spring implémente le Service au démarrage
180 )))
181 1. (((
182 et @OverrideXXX → Pour que l'implémentation surcharge le service par défaut
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
187 1. Sans IDE, penser à ajouter les imports suivant :
188 11. import org.springframework.stereotype.Service;
189 11. import fr.univlorraine.hypercerts.apogee.services.annotations.OverrideXXX;
190 \\
191
192 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
193 /**
194 * Override default ApogeeUtilisateurService implementation.
195 * >> README
196 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUtilisateurService pour que l'implémentation soit utilisée.
197 *
198 * @author Matthieu Manginot
199 */
200 @NoArgsConstructor
201 @Slf4j
202 // @Service
203 // @OverrideApogeeUtilisateurService
204 public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
205
206 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
207 private EntityManager entityManagerApogee;
208
209 @PostConstruct
210 public void init() {
211 log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
212 }
213
214 /**
215 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
216 */
217 @Override
218 public String getMail(final String uidApogee) {
219 /* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
220 return null;
221 }
222 }
223 {{/code}}
224
225 === Paramétrage de Digiposte ===
226
227 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
228
229 //Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
230
231 === Maven / Exécution de l'applicatoin ===
232
233 * Sous un IDE, exemple Eclipse//, avec fichier de config à la racine contenant les sources// :
234 ** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
235 * Lancer l'application (hors d'un IDE),// avec fichier de config à la racine contenant les sources// :
236
237 {{code language="bash" theme="Eclipse"}}
238 mvn spring-boot:run
239 {{/code}}
240
241 * Lancer les tests :
242
243 {{code language="bash" theme="Eclipse"}}
244 mvn verify
245 {{/code}}
246
247 * Créer le package pour production :
248
249 {{code language="bash" theme="Eclipse"}}
250 mvn clean package -Pproduction
251 {{/code}}
252
253 * 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 :
254
255 {{code language="bash" theme="Eclipse"}}
256 export JAVA_OPTS="$JAVA_OPTS -Dspring.config.location=$HOMEDIR/application.yaml"
257 {{/code}}
258
259 === Administration ===
260
261 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
262
263 === Gestion ===
264
265 \\
266
267 |=(((
268 Vue
269 )))|=(((
270 Utilisation
271 )))
272 |(((
273 (% class="content-wrapper" %)
274 (((
275 [[image:attach:image2021-2-23_10-42-24.png||height="400"]]
276 )))
277 )))|(((
278 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
279
280 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
281
282 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
283
284 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
285 )))
286
287 === Loggers ===
288
289 \\
290
291 |=(((
292 Vue
293 )))|=(((
294 Utilisation
295 )))
296 |(((
297 (% class="content-wrapper" %)
298 (((
299 [[image:attach:image2021-2-23_10-42-53.png||height="400"]]
300 )))
301 )))|(((
302 Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
303
304 Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
305 )))