Code source wiki de Documentation technique

Version 9.1 par Cédric Champmartin le 23/07/2020 - 15: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. Elle requiert l'utilisation d'une base MariaDB pour son fonctionnement interne. Elle se déploie sur des serveurs comme une application SpringBoot classique. Le WAR pourra être pris en charge par un tomcat et servir les utilisateur•ices via l'URL configurée.
8
9 |=(((
10 Technologie
11 )))|=(((
12 Version
13 )))
14 |(((
15 JDK
16 )))|(((
17 11+
18 )))
19 |(% colspan="1" %)(((
20 SpringBoot
21 )))|(% colspan="1" %)(((
22 2.3
23 )))
24 |(% colspan="1" %)(((
25 Vaadin (Frontend)
26 )))|(% colspan="1" %)(((
27 14
28 )))
29 |(((
30 Tomcat
31 )))|(((
32 9+
33 )))
34 |(% colspan="1" %)(((
35 MariaDB
36 )))|(% colspan="1" %)(((
37 14+
38 )))
39 |(% colspan="1" %)(((
40 Maven
41 )))|(% colspan="1" %)(((
42 3.6+
43 )))
44 |(% colspan="1" %)(((
45 Connection Apogée
46 )))|(% colspan="1" %)(((
47 \\
48 )))
49 |(% colspan="1" %)(((
50 Connection Apogée via WS
51 )))|(% colspan="1" %)(((
52 \\
53 )))
54 |(% colspan="1" %)(((
55 Connection LDAP
56 )))|(% colspan="1" %)(((
57 \\
58 )))
59 |(% colspan="1" %)(((
60 Docker (optionnel)
61 )))|(% colspan="1" %)(((
62 docker-compose 3
63 )))
64
65 == Téléchargement des sources ==
66
67 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"]].
68
69 == Installation d'Hypercerts ==
70
71 === **Initialisation de la base** ===
72
73 La base de données MariaDB/MySQL s'initialise avec la commande Flyway suivante :
74
75 {{code language="bash" theme="Eclipse"}}
76 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
77 {{/code}}
78
79 Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
80
81 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
82 # Flyway
83 # ConfigFiles : https://flywaydb.org/documentation/configfiles
84 # mvn -Dflyway.configFiles=xxx.properties flyway:migrate
85 flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
86 flyway.schemas=hypercerts
87 flyway.user=XXX
88 flyway.password=
89 # Emplacement des fichiers sql de migration
90 flyway.locations=classpath:db/migration
91 # baselineOnMigrate
92 flyway.baselineOnMigrate=false
93 {{/code}}
94
95 Au besoin, les fichiers sql de migration peuvent être trouvés sous //src/main/resources/db/migration//.
96
97 Pour remettre à zéro la base, lancer le script //src/main/resources/db/reset/reset.sql //puis exécuter à nouveau Flyway//.//
98
99 === Configuration de l'application ===
100
101 Créer et compléter un fichier **application.yaml** à la racine du projet sur le modèle de **application-sample.yaml**
102
103 Des indications sont présentes dans le fichier pour aider à sa configuration.
104
105 === **Éléments de configuration importants** ===
106
107 ==== Property //app.production// ====
108
109 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.
110
111 En étant à false, cette property autorise également l'interception de tous les mails applicatifs.
112
113 ==== **Envoi de mail** ====
114
115 (% 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é :__
116
117 * d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/||shape="rect"]]) en remplacement de votre smtp
118 * ou de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
119 ** **app.production** à false
120 ** **spring.mail.intercept.active** à true
121 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
122
123 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.
124
125 ==== WebServices Apogée ====
126
127 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
128
129 Les properties différent du classique configUrlServices.properties de l'AMUE.
130
131 Des headers peuvent être ajoutés en paramètre de chaque WebService.
132
133 Exemple :
134
135 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
136 ws:
137 apogee:
138 administratif:
139 url: https://api.univ.fr/apo/amue_apo_administratif
140 headers:
141 # header1: value1
142 # header2: value2
143 username: xxxx
144 password: xxxx
145 {{/code}}
146
147 === Configurer et lancer le projet dans Eclipse ===
148
149 * Importer le projet Maven dans eclipse.
150 * 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'.
151
152 === Customisation des services ===
153
154 Plusieurs services sont personnalisables en fonction de votre environnement.
155
156 Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
157
158 * ApogeeUserServiceCustomExample
159 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid LDAP
160 * BlocageServiceCustomExample
161 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
162 * ComposanteServiceCustomExample
163 ** Personnalisation de la récupération :
164 *** de toutes les composantes
165 *** des composantes pour un utilisateur à partir de l'uid LDAP
166 *** du nombre de composantes pour un utilisateur à partir de l'uid LDAP
167
168 Pour personnaliser un de ces services :
169
170 1. Copier la classe en la renommant
171 1. Implémenter la ou les méthodes
172 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
173 1. (((
174 Dé-commenter les 2 annotations :1. (((
175 @Service → Pour que Spring implémente le Service au démarrage
176 )))
177 1. (((
178 et @Override~*~* → Pour que l'implémentation surcharge le service par défaut
179 )))
180 )))
181 1. Au démarrage de l'application
182 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
183
184 Exemple :
185
186 {{code language="java" theme="Eclipse" linenumbers="true" collapse="true"}}
187 /**
188 * Override default ApogeeUserService implementation.
189 * >> README
190 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUserService pour que l'implémentation soit utilisée.
191 *
192 * @author Matthieu Manginot
193 */
194 @NoArgsConstructor
195 @Slf4j
196 @Service
197 @OverrideApogeeUserService
198 public class ApogeeUserServicePERSO implements IApogeeUserService {
199
200 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
201 private EntityManager entityManagerApogee;
202
203 @PostConstruct
204 public void init() {
205 log.info("Overriding {} for IApogeeUserService implementation", getClass().getCanonicalName());
206 }
207
208 /**
209 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUserService#getEmail(java.lang.String)
210 */
211 @Override
212 public String getEmail(final String uidLdap) {
213 /* Implémentation personnalisée de getEmail. entityManagerApogee.createNativeQuery... */
214 return "mail@univ.fr";
215 }
216 }
217 {{/code}}
218
219 ===
220 Paramétrage de Digiposte ===
221
222 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
223
224 === Tâches Maven ===
225
226 * Lancer l'application (hors d'un IDE) :
227
228 {{code language="bash" theme="Eclipse"}}
229 mvn spring-boot:run
230 {{/code}}
231
232 * Lancer les tests :
233
234 {{code language="bash" theme="Eclipse"}}
235 mvn verify
236 {{/code}}
237
238 * Créer le package pour production :
239
240 {{code language="bash" theme="Eclipse"}}
241 mvn clean package -Pproduction
242 {{/code}}
243
244 === Makefile ===
245
246 Un Makefile est également disponible. A la racine, utilisez `make help` pour obtenir les commandes disponibles.
247
248 == Administration ==
249
250 Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.
251
252 [[image:attach:image2020-7-23_12-41-56.png||align="center" height="400"]]
253
254 === Gestion ===
255
256 \\
257
258 |=(((
259 Vue
260 )))|=(((
261 Utilisation
262 )))
263 |(((
264 (% class="content-wrapper" %)
265 (((
266 [[image:attach:image2020-7-23_12-51-28.png||height="400"]]
267 )))
268 )))|(((
269 Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.
270
271 Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.
272
273 On peut aussi utiliser des boutons pour lancer plus finement des tâches.
274
275 À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.
276 )))