Code source wiki de Documentation technique

Version 11.1 par Matthieu Manginot le 23/07/2020 - 15:47
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 \\
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
70 Les sources de l'application peuvent être téléchargées à [[cet endroit>>url:ftp://dufour18@download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.2-SNAPSHOT.zip||shape="rect"]].
71
72 == Installation d'Hypercerts ==
73
74 === **Initialisation de la base** ===
75
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 :
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
100 Pour remettre à zéro la base, lancer le script //src/main/resources/db/reset/reset.sql //puis exécuter à nouveau Flyway//.//
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
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.
113
114 En étant à false, cette property autorise également l'interception de tous les mails applicatifs.
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
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
124 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
125
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 sont en copie de cette property. Elle peut être laissée vide.
127
128 ==== WebServices Apogée ====
129
130 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
131
132 Les properties différent du classique configUrlServices.properties de l'AMUE.
133
134 Des headers peuvent être ajoutés en paramètre de chaque WebService.
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
152 * Importer le projet Maven dans eclipse.
153 * Lorsque la configuration est terminée, démarrer l'application en faisant un clic droit sur {{code language="none"}}fr.univlorraine.hypercerts.Application.java{{/code}} et en choisissant 'Run As / Java Application'.
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
161 * ApogeeUserServiceCustomExample
162 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid LDAP
163 * BlocageServiceCustomExample
164 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
165 * ComposanteServiceCustomExample
166 ** Personnalisation de la récupération :
167 *** de toutes les composantes
168 *** des composantes pour un utilisateur à partir de l'uid LDAP
169 *** du nombre de composantes pour un utilisateur à partir de l'uid LDAP
170
171 Pour personnaliser un de ces services :
172
173 1. Copier la classe en la renommant
174 1. Implémenter la ou les méthodes
175 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
176 1. (((
177 Dé-commenter les 2 annotations :1. (((
178 @Service → Pour que Spring implémente le Service au démarrage
179 )))
180 1. (((
181 et @Override~*~* → Pour que l'implémentation surcharge le service par défaut
182 )))
183 )))
184 1. Au démarrage de l'application
185 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
186
187 Exemple :
188
189 {{code language="java" theme="Eclipse" linenumbers="true" collapse="true"}}
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
222 ===
223 Paramétrage de Digiposte ===
224
225 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
226
227 === Tâches Maven ===
228
229 * Lancer l'application (hors d'un IDE) :
230
231 {{code language="bash" theme="Eclipse"}}
232 mvn spring-boot:run
233 {{/code}}
234
235 * Lancer les tests :
236
237 {{code language="bash" theme="Eclipse"}}
238 mvn verify
239 {{/code}}
240
241 * Créer le package pour production :
242
243 {{code language="bash" theme="Eclipse"}}
244 mvn clean package -Pproduction
245 {{/code}}
246
247 === Makefile ===
248
249 Un Makefile est également disponible. A la racine, utilisez `make help` pour obtenir les commandes disponibles.
250
251 == Administration ==
252
253 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
254
255 [[image:attach:image2020-7-23_12-41-56.png||align="center" height="400"]]
256
257 === Gestion ===
258
259 \\
260
261 |=(((
262 Vue
263 )))|=(((
264 Utilisation
265 )))
266 |(((
267 (% class="content-wrapper" %)
268 (((
269 [[image:attach:image2020-7-23_12-51-28.png||height="400"]]
270 )))
271 )))|(((
272 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
273
274 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
275
276 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
277
278 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
279 )))