Aller au contenu

Code source wiki de 01 - Documentation technique

Version 37.1 par Matthieu Manginot le 17/03/2021 - 10:24
Masquer les derniers auteurs
Cédric Champmartin 9.1 1
2
3 {{toc/}}
4
Cédric Champmartin 2.1 5 == Prérequis ==
6
Matthieu Manginot 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.
Cédric Champmartin 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" %)(((
Cédric Champmartin 1.1 50 \\
Cédric Champmartin 2.1 51 )))
52 |(% colspan="1" %)(((
53 Connection Apogée via WS
54 )))|(% colspan="1" %)(((
Matthieu Manginot 21.1 55 6.00.50
Cédric Champmartin 2.1 56 )))
57 |(% colspan="1" %)(((
58 Connection LDAP
59 )))|(% colspan="1" %)(((
60 \\
61 )))
62
63 == Téléchargement des sources ==
64
Matthieu Manginot 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"]]
Cédric Champmartin 2.1 66
67 == Installation d'Hypercerts ==
68
Matthieu Manginot 27.1 69 === **Initialisation / Mise à jour de la base** ===
Cédric Champmartin 2.1 70
Matthieu Manginot 27.1 71 La base "//hypercerts//" MariaDB/MySQL s'initialise / se met à jour avec la commande Flyway suivante :
Cédric Champmartin 2.1 72
73 {{code language="bash" theme="Eclipse"}}
74 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
75 {{/code}}
76
Matthieu Manginot 33.1 77 Le fichier **flyway.properties doit être créé** à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
Cédric Champmartin 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
Matthieu Manginot 36.1 93 Au besoin, les fichiers sql de migration peuvent être trouvés sous **src/main/resources/db/migration**.
Cédric Champmartin 2.1 94
Matthieu Manginot 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//.//
Cédric Champmartin 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
Matthieu Manginot 33.1 101 Des indications sont présentes dans le fichier pour aider à sa configuration ou **ci-dessous**.
Cédric Champmartin 2.1 102
Matthieu Manginot 33.1 103 === Maven / Exécution de l'application ===
Cédric Champmartin 2.1 104
Matthieu Manginot 35.1 105 * Sous un IDE, exemple Eclipse//, avec fichier de configuration à la racine// :
Matthieu Manginot 33.1 106 ** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
Matthieu Manginot 35.1 107 * Lancer l'application (hors d'un IDE),// avec fichier de configuration à la racine// :
Matthieu Manginot 32.1 108
Matthieu Manginot 33.1 109 {{code language="bash" theme="Eclipse"}}
110 mvn spring-boot:run
111 {{/code}}
Matthieu Manginot 32.1 112
Matthieu Manginot 33.1 113 * Lancer les tests :
Matthieu Manginot 32.1 114
Matthieu Manginot 33.1 115 {{code language="bash" theme="Eclipse"}}
116 mvn verify
117 {{/code}}
Matthieu Manginot 32.1 118
Matthieu Manginot 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
Matthieu Manginot 36.1 131 == (% style="letter-spacing: -0.006em;" %)**Configuration**(%%) ==
Matthieu Manginot 33.1 132
Matthieu Manginot 34.1 133 === Property //app.production// ===
Cédric Champmartin 2.1 134
Matthieu Manginot 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.
Cédric Champmartin 2.1 136
Matthieu Manginot 37.1 137 En étant à **false**, cette **property **autorise également la configuration de l'interception de tout les mails applicatifs.
Cédric Champmartin 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
Matthieu Manginot 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//
Cédric Champmartin 2.1 147 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
148
Matthieu Manginot 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.
Cédric Champmartin 2.1 150
Matthieu Manginot 34.1 151 === WebServices Apogée ===
Cédric Champmartin 2.1 152
153 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
154
Matthieu Manginot 36.1 155 Les **properties **différent du classique fichier de configuration **configUrlServices.properties** de l'AMUE.
Cédric Champmartin 2.1 156
Matthieu Manginot 36.1 157 Des **headers **peuvent être ajoutés en paramètre de chaque WebServices.
Cédric Champmartin 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
Matthieu Manginot 35.1 173 === Customisation des templates de mail ===
174
Matthieu Manginot 37.1 175 Les properties suivantes servent à indiquer les templates personnalisés :
Matthieu Manginot 35.1 176
Matthieu Manginot 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
Cédric Champmartin 2.1 184 === Customisation des services ===
185
186 Plusieurs services sont personnalisables en fonction de votre environnement.
187
Matthieu Manginot 36.1 188 Sous **fr.univlorraine.hypercerts.apogee.service.customs** :
Cédric Champmartin 2.1 189
Matthieu Manginot 36.1 190 * **ApogeeUtilisateurServiceCustomExample//
191 //**
Matthieu Manginot 25.1 192 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
Matthieu Manginot 36.1 193 * **ApogeeBlocageServiceCustomExample//
194 //**
Cédric Champmartin 2.1 195 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
Matthieu Manginot 36.1 196 * **ApogeeComposanteServiceCustomExample//
197 //**
Cédric Champmartin 2.1 198 ** Personnalisation de la récupération :
Matthieu Manginot 15.1 199 *** de toutes les composantes 
200 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
Matthieu Manginot 25.1 201 *** des composantes pour un utilisateur à partir de l'uid Apogée
202 *** du nombre de composantes pour un utilisateur à partir de l'uid Apogée
Matthieu Manginot 36.1 203 * **ApogeeUidServiceCustomExample**\\
Matthieu Manginot 25.1 204 ** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
Cédric Champmartin 2.1 205
Matthieu Manginot 15.1 206 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
Cédric Champmartin 2.1 207
208 1. Copier la classe en la renommant
209 1. Implémenter la ou les méthodes
210 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
211 1. (((
212 Dé-commenter les 2 annotations :1. (((
Matthieu Manginot 36.1 213 **@Service** → Pour que Spring implémente le Service au démarrage
Cédric Champmartin 2.1 214 )))
215 1. (((
Matthieu Manginot 36.1 216 et **@OverrideXXX** → Pour que l'implémentation surcharge le service par défaut
Cédric Champmartin 2.1 217 )))
218 )))
219 1. Au démarrage de l'application
220 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
Matthieu Manginot 25.1 221 1. Sans IDE, penser à ajouter les imports suivant :
222 11. import org.springframework.stereotype.Service;
Matthieu Manginot 37.1 223 11. import fr.univlorraine.hypercerts.apogee.services.annotations.**OverrideXXX**;
Matthieu Manginot 15.1 224 \\
Cédric Champmartin 2.1 225
Matthieu Manginot 15.1 226 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
Cédric Champmartin 2.1 227 /**
Matthieu Manginot 26.1 228 * Override default ApogeeUtilisateurService implementation.
Cédric Champmartin 2.1 229 * >> README
Matthieu Manginot 26.1 230 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUtilisateurService pour que l'implémentation soit utilisée.
Cédric Champmartin 2.1 231 *
232 * @author Matthieu Manginot
233 */
234 @NoArgsConstructor
235 @Slf4j
Matthieu Manginot 26.1 236 // @Service
237 // @OverrideApogeeUtilisateurService
238 public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
Cédric Champmartin 2.1 239
240 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
241 private EntityManager entityManagerApogee;
242
243 @PostConstruct
244 public void init() {
Matthieu Manginot 26.1 245 log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
Cédric Champmartin 2.1 246 }
247
248 /**
Matthieu Manginot 26.1 249 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
Cédric Champmartin 2.1 250 */
251 @Override
Matthieu Manginot 26.1 252 public String getMail(final String uidApogee) {
253 /* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
254 return null;
Cédric Champmartin 2.1 255 }
256 }
257 {{/code}}
258
Matthieu Manginot 15.1 259 === Paramétrage de Digiposte ===
Cédric Champmartin 2.1 260
Matthieu Manginot 3.1 261 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
Cédric Champmartin 2.1 262
Matthieu Manginot 15.1 263 //Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
264
Matthieu Manginot 34.1 265 == (% style="letter-spacing: -0.006em;" %)Administration(%%) ==
Cédric Champmartin 2.1 266
Cédric Champmartin 9.1 267 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
268
Cédric Champmartin 8.1 269 === Gestion ===
270
271 \\
272
273 |=(((
274 Vue
275 )))|=(((
276 Utilisation
277 )))
278 |(((
279 (% class="content-wrapper" %)
280 (((
Matthieu Manginot 31.1 281 [[image:attach:image2021-2-23_10-42-24.png||height="400"]]
Cédric Champmartin 8.1 282 )))
283 )))|(((
284 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
285
286 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
287
288 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
289
290 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
291 )))
Matthieu Manginot 16.1 292
293 === Loggers ===
294
295 \\
296
297 |=(((
298 Vue
299 )))|=(((
300 Utilisation
301 )))
302 |(((
303 (% class="content-wrapper" %)
304 (((
Matthieu Manginot 31.1 305 [[image:attach:image2021-2-23_10-42-53.png||height="400"]]
Matthieu Manginot 16.1 306 )))
307 )))|(((
308 Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
309
Matthieu Manginot 31.1 310 Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
Matthieu Manginot 16.1 311 )))