Code source wiki de 01 - Documentation technique

Version 38.1 par Matthieu Manginot le 17/03/2021 - 11:31
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 ou **ci-dessous**.
102
103 === Maven / Exécution de l'application ===
104
105 * Sous un IDE, exemple Eclipse//, avec fichier de configuration à la racine// :
106 ** (% style="color: rgb(0,0,0);" %)Clic droit sur "Application.java > Run As > Java Application"
107 * Lancer l'application (hors d'un IDE),// avec fichier de configuration à la racine// :
108
109 {{code language="bash" theme="Eclipse"}}
110 mvn spring-boot:run
111 {{/code}}
112
113 * Lancer les tests :
114
115 {{code language="bash" theme="Eclipse"}}
116 mvn verify
117 {{/code}}
118
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
131 == (% style="letter-spacing: -0.006em;" %)**Configuration**(%%) ==
132
133 === Property //app.production// ===
134
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.
136
137 En étant à **false**, cette **property **autorise également la configuration de l'interception de tout les mails applicatifs.
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
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//
147 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
148
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.
150
151 === WebServices Apogée ===
152
153 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
154
155 Les **properties **différent du classique fichier de configuration **configUrlServices.properties** de l'AMUE.
156
157 Des **headers **peuvent être ajoutés en paramètre de chaque WebServices.
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
173 === Customisation des templates de mail ===
174
175 Les properties suivantes servent à indiquer les templates personnalisés :
176
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
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
192 === Customisation des services ===
193
194 Plusieurs services sont personnalisables en fonction de votre environnement.
195
196 Sous **fr.univlorraine.hypercerts.apogee.service.customs** :
197
198 * **ApogeeUtilisateurServiceCustomExample//
199 //**
200 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
201 * **ApogeeBlocageServiceCustomExample//
202 //**
203 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
204 * **ApogeeComposanteServiceCustomExample//
205 //**
206 ** Personnalisation de la récupération :
207 *** de toutes les composantes 
208 **** → utilisé pour donner les droits sur toutes les composantes aux super admins
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
211 * **ApogeeUidServiceCustomExample**\\
212 ** Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son uid Ldap
213
214 (% style="color: rgb(0,51,102);" %)__Pour personnaliser un de ces services :__
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. (((
221 **@Service** → Pour que Spring implémente le Service au démarrage
222 )))
223 1. (((
224 et **@OverrideXXX** → Pour que l'implémentation surcharge le service par défaut
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
229 1. Sans IDE, penser à ajouter les imports suivant :
230 11. import org.springframework.stereotype.Service;
231 11. import fr.univlorraine.hypercerts.apogee.services.annotations.**OverrideXXX**;
232 \\
233
234 {{code language="java" theme="Eclipse" title="Exemple" linenumbers="true" collapse="true"}}
235 /**
236 * Override default ApogeeUtilisateurService implementation.
237 * >> README
238 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUtilisateurService pour que l'implémentation soit utilisée.
239 *
240 * @author Matthieu Manginot
241 */
242 @NoArgsConstructor
243 @Slf4j
244 // @Service
245 // @OverrideApogeeUtilisateurService
246 public class ApogeeUtilisateurServiceCustomExample implements IApogeeUtilisateurService {
247
248 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
249 private EntityManager entityManagerApogee;
250
251 @PostConstruct
252 public void init() {
253 log.info("Overriding {} for IApogeeUtilisateurService implementation", getClass().getCanonicalName());
254 }
255
256 /**
257 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
258 */
259 @Override
260 public String getMail(final String uidApogee) {
261 /* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
262 return null;
263 }
264 }
265 {{/code}}
266
267 === Paramétrage de Digiposte ===
268
269 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
270
271 //Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.//
272
273 == (% style="letter-spacing: -0.006em;" %)Administration(%%) ==
274
275 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
276
277 === Gestion ===
278
279 \\
280
281 |=(((
282 Vue
283 )))|=(((
284 Utilisation
285 )))
286 |(((
287 (% class="content-wrapper" %)
288 (((
289 [[image:attach:image2021-2-23_10-42-24.png||height="400"]]
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 )))
300
301 === Loggers ===
302
303 \\
304
305 |=(((
306 Vue
307 )))|=(((
308 Utilisation
309 )))
310 |(((
311 (% class="content-wrapper" %)
312 (((
313 [[image:attach:image2021-2-23_10-42-53.png||height="400"]]
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
318 Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.
319 )))