Code source wiki de 01 - Documentation technique

Version 41.1 par Matthieu Manginot le 19/03/2021 - 11:47
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.
Cédric Champmartin 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" %)(((
Cédric Champmartin 1.1 49 \\
Cédric Champmartin 2.1 50 )))
51 |(% colspan="1" %)(((
52 Connection Apogée via WS
53 )))|(% colspan="1" %)(((
Matthieu Manginot 21.1 54 6.00.50
Cédric Champmartin 2.1 55 )))
56 |(% colspan="1" %)(((
57 Connection LDAP
58 )))|(% colspan="1" %)(((
59 \\
60 )))
61
62 == Téléchargement des sources ==
63
Matthieu Manginot 28.1 64 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 65
66 == Installation d'Hypercerts ==
67
Matthieu Manginot 27.1 68 === **Initialisation / Mise à jour de la base** ===
Cédric Champmartin 2.1 69
Matthieu Manginot 39.1 70 La base **hypercerts **MariaDB/MySQL s'initialise / se met à jour avec la commande **Flyway** suivante :
Cédric Champmartin 2.1 71
72 {{code language="bash" theme="Eclipse"}}
73 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
74 {{/code}}
75
Matthieu Manginot 33.1 76 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 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
Matthieu Manginot 36.1 92 Au besoin, les fichiers sql de migration peuvent être trouvés sous **src/main/resources/db/migration**.
Cédric Champmartin 2.1 93
Matthieu Manginot 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**//.//
Cédric Champmartin 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
Matthieu Manginot 33.1 100 Des indications sont présentes dans le fichier pour aider à sa configuration ou **ci-dessous**.
Cédric Champmartin 2.1 101
Matthieu Manginot 33.1 102 === Maven / Exécution de l'application ===
Cédric Champmartin 2.1 103
Matthieu Manginot 39.1 104 * **Sous un** **IDE**, exemple Eclipse//, //**avec le fichier de configuration à la racine** :
Matthieu Manginot 33.1 105 ** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
Matthieu Manginot 39.1 106 * Lancer l'application (**hors d'un IDE**),// //**avec fichier de configuration à la racine** :
Matthieu Manginot 32.1 107
Matthieu Manginot 33.1 108 {{code language="bash" theme="Eclipse"}}
109 mvn spring-boot:run
110 {{/code}}
Matthieu Manginot 32.1 111
Matthieu Manginot 33.1 112 * Lancer les tests :
Matthieu Manginot 32.1 113
Matthieu Manginot 33.1 114 {{code language="bash" theme="Eclipse"}}
115 mvn verify
116 {{/code}}
Matthieu Manginot 32.1 117
Matthieu Manginot 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
Matthieu Manginot 36.1 130 == (% style="letter-spacing: -0.006em;" %)**Configuration**(%%) ==
Matthieu Manginot 33.1 131
Matthieu Manginot 34.1 132 === Property //app.production// ===
Cédric Champmartin 2.1 133
Matthieu Manginot 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.
Cédric Champmartin 2.1 135
Matthieu Manginot 39.1 136 En étant à **false**, cette **property **autorise également la configuration de l'interception de tous les mails applicatifs.
Cédric Champmartin 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
Matthieu Manginot 13.1 143 * **ou** de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
144 ** **app.production** à //false//
145 ** **spring.mail.intercept.active** à //true//
Cédric Champmartin 2.1 146 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
147
Matthieu Manginot 36.1 148 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 149
Matthieu Manginot 34.1 150 === WebServices Apogée ===
Cédric Champmartin 2.1 151
152 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
153
Matthieu Manginot 36.1 154 Les **properties **différent du classique fichier de configuration **configUrlServices.properties** de l'AMUE.
Cédric Champmartin 2.1 155
Matthieu Manginot 36.1 156 Des **headers **peuvent être ajoutés en paramètre de chaque WebServices.
Cédric Champmartin 2.1 157
158 Exemple :
159
160 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
161 ws:
162 apogee:
163 administratif:
164 url: https://api.univ.fr/apo/amue_apo_administratif
165 headers:
166 # header1: value1
167 # header2: value2
168 username: xxxx
169 password: xxxx
170 {{/code}}
171
Matthieu Manginot 35.1 172 === Customisation des templates de mail ===
173
Matthieu Manginot 37.1 174 Les properties suivantes servent à indiquer les templates personnalisés :
Matthieu Manginot 35.1 175
Matthieu Manginot 37.1 176 * spring.mail.templateName.**attestation** : pour le mail à destination de l'étudiant contenant l'attestation
177 * spring.mail.templateName.**creationDigiposte** : pour le mail à destination de l'étudiant envoyé après la création du coffre Digiposte
178 * spring.mail.templateName.**creationCampagne** : pour le mail d'une nouvelle campagne (à destination du gestionnaire qui a lancé la campagne)
179 * spring.mail.templateName.**reportCampagne** : pour le mail de rapport de campagne (à destination du gestionnaire qui a lancé la campagne)
180
181 ❓ Par défaut, les valeurs sont vides et les templates par défaut de l'application sont utilisés
182
Matthieu Manginot 38.1 183 Pour customiser un template :
184
185 * **Copier et renommer un template HTML** présent sous **src/main/resources/templates**
186 * Par exemple pour le mail d'attestation :
187 ** Renommer** mail-attestation.html** en **mail-attestation-custom.html**
188 ** Adapter le template
189 ** Dans la config, saisir spring.mail.templateName.**attestation **: **mail-attestation-custom.html**
190
Cédric Champmartin 2.1 191 === Customisation des services ===
192
193 Plusieurs services sont personnalisables en fonction de votre environnement.
194
Matthieu Manginot 36.1 195 Sous **fr.univlorraine.hypercerts.apogee.service.customs** :
Cédric Champmartin 2.1 196
Matthieu Manginot 36.1 197 * **ApogeeUtilisateurServiceCustomExample//
198 //**
Matthieu Manginot 25.1 199 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
Matthieu Manginot 36.1 200 * **ApogeeBlocageServiceCustomExample//
201 //**
Cédric Champmartin 2.1 202 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
Matthieu Manginot 36.1 203 * **ApogeeComposanteServiceCustomExample//
204 //**
Cédric Champmartin 2.1 205 ** Personnalisation de la récupération :
Matthieu Manginot 15.1 206 *** de toutes les composantes 
207 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
Matthieu Manginot 25.1 208 *** des composantes pour un utilisateur à partir de l'uid Apogée
209 *** du nombre de composantes pour un utilisateur à partir de l'uid Apogée
Matthieu Manginot 36.1 210 * **ApogeeUidServiceCustomExample**\\
Matthieu Manginot 25.1 211 ** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
Cédric Champmartin 2.1 212
Matthieu Manginot 15.1 213 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
Cédric Champmartin 2.1 214
215 1. Copier la classe en la renommant
216 1. Implémenter la ou les méthodes
217 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
218 1. (((
219 Dé-commenter les 2 annotations :1. (((
Matthieu Manginot 36.1 220 **@Service** → Pour que Spring implémente le Service au démarrage
Cédric Champmartin 2.1 221 )))
222 1. (((
Matthieu Manginot 36.1 223 et **@OverrideXXX** → Pour que l'implémentation surcharge le service par défaut
Cédric Champmartin 2.1 224 )))
225 )))
226 1. Au démarrage de l'application
227 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
Matthieu Manginot 25.1 228 1. Sans IDE, penser à ajouter les imports suivant :
229 11. import org.springframework.stereotype.Service;
Matthieu Manginot 37.1 230 11. import fr.univlorraine.hypercerts.apogee.services.annotations.**OverrideXXX**;
Matthieu Manginot 15.1 231 \\
Cédric Champmartin 2.1 232
Matthieu Manginot 15.1 233 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
Cédric Champmartin 2.1 234 /**
Matthieu Manginot 26.1 235 * Override default ApogeeUtilisateurService implementation.
Cédric Champmartin 2.1 236 * >> README
Matthieu Manginot 26.1 237 * 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 238 *
239 * @author Matthieu Manginot
240 */
241 @NoArgsConstructor
242 @Slf4j
Matthieu Manginot 26.1 243 // @Service
244 // @OverrideApogeeUtilisateurService
245 public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
Cédric Champmartin 2.1 246
247 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
248 private EntityManager entityManagerApogee;
249
250 @PostConstruct
251 public void init() {
Matthieu Manginot 26.1 252 log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
Cédric Champmartin 2.1 253 }
254
255 /**
Matthieu Manginot 26.1 256 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
Cédric Champmartin 2.1 257 */
258 @Override
Matthieu Manginot 26.1 259 public String getMail(final String uidApogee) {
260 /* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
261 return null;
Cédric Champmartin 2.1 262 }
263 }
264 {{/code}}
265
Matthieu Manginot 40.1 266 === Configuration de Digiposte ===
Cédric Champmartin 2.1 267
Matthieu Manginot 40.1 268 Dans **application.yaml** sous **digiposte.***
269
270 * **digiposte**
271 ** **codeDistributeur** : Code distributeur Digiposte (fourni par Digiposte)
272 ** **codeEmetteur** : Code emetteur Digiposte (PID) (fourni par Digiposte)
273 ** **type** : Type de campagne : en mode OPT-IN = PREINSCRIPTION ou mode OPT-OUT = PREINSCRIPTION_WITH_VALIDATED_MEMBERSHIP (param Digiposte)
274 ** **sendMailHypercerts** : Envoi du mail Hypercerts pour informer l'étudiant qu'un coffre Digiposte est crée
275 ** **docDigiposteEtudiant** : Url de la documentation Digiposte pour les étudiants présente dans le mail d'information
276 ** **sendMailDigiposte** : Envoi du mail Digiposte : 'YES' ou 'NO' (param Digiposte)
277 ** **checkMailMode** : Vérification du mail : mail vérifié par l'émetteur = CHECKED ou mail non vérifié = INFORMATION (param Digiposte)
278 ** **urlAccesDirect** : Urls d'accès direct à Digiposte pour les adhésions ou les résiliations\\
279 *** **adhesions** : Url pour les adhésions directes
280 *** **resiliations** : Url pour les résiliations directes
281 ** **adhesions** : Configuration de l'envoi des adhésions (création des coffres)\\
282 *** **ftp** : Connexion au sftp Digiposte des adhésions
283 *** **ws** : Connexion au ws Digiposte
284 ** **routages** : Configuration de l'envoi des routages (dépôt des attestations dans les coffres)
285 *** **ftp **: Connexion au sftp Digiposte des routages
286 *** **publisher** : Configuration du publisher : Clé publique pour la sécurisation des routages
Matthieu Manginot 41.1 287 \\
Matthieu Manginot 40.1 288
Matthieu Manginot 41.1 289 {{info}}
290 Une fois configuré, il faudra activer Digiposte avec la property **app.usingDigiposteDelivery : true**
291 {{/info}}
292
Matthieu Manginot 39.1 293 \\
Cédric Champmartin 2.1 294
Matthieu Manginot 41.1 295 \\
296
Matthieu Manginot 40.1 297 ----
298
Matthieu Manginot 34.1 299 == (% style="letter-spacing: -0.006em;" %)Administration(%%) ==
Cédric Champmartin 2.1 300
Cédric Champmartin 9.1 301 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
302
Cédric Champmartin 8.1 303 === Gestion ===
304
305 \\
306
307 |=(((
308 Vue
309 )))|=(((
310 Utilisation
311 )))
312 |(((
313 (% class="content-wrapper" %)
314 (((
Matthieu Manginot 31.1 315 [[image:attach:image2021-2-23_10-42-24.png||height="400"]]
Cédric Champmartin 8.1 316 )))
317 )))|(((
318 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
319
320 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
321
322 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
323
324 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
325 )))
Matthieu Manginot 16.1 326
327 === Loggers ===
328
329 \\
330
331 |=(((
332 Vue
333 )))|=(((
334 Utilisation
335 )))
336 |(((
337 (% class="content-wrapper" %)
338 (((
Matthieu Manginot 31.1 339 [[image:attach:image2021-2-23_10-42-53.png||height="400"]]
Matthieu Manginot 16.1 340 )))
341 )))|(((
342 Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.
343
Matthieu Manginot 31.1 344 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 345 )))