Documentation technique

Version 6.1 par Matthieu Manginot le 23/07/2020 - 14:35

Prérequis

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.

Technologie

Version

JDK

11+

SpringBoot

2.3

Vaadin (Frontend)

14

Tomcat

9+

MariaDB

14+

Maven

3.6+

Connection Apogée


Connection Apogée via WS


Connection LDAP


Docker (optionnel)

docker-compose 3

Téléchargement des sources

Les sources de l'application peuvent être téléchargées à cet endroit.

Installation d'Hypercerts

Initialisation de la base

La base de données MariaDB/MySQL s'initialise avec la commande Flyway suivante :

mvn -Dflyway.configFiles=flyway.properties flyway:migrate

Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway. 

# Flyway
# ConfigFiles : https://flywaydb.org/documentation/configfiles
# mvn -Dflyway.configFiles=xxx.properties flyway:migrate
flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
flyway.schemas=hypercerts
flyway.user=XXX
flyway.password=
# Emplacement des fichiers sql de migration
flyway.locations=classpath:db/migration
# baselineOnMigrate
flyway.baselineOnMigrate=false

Au besoin, les fichiers sql de migration peuvent être trouvés sous src/main/resources/db/migration.

Pour remettre à zéro la base, lancer le script src/main/resources/db/reset/reset.sql puis exécuter à nouveau Flyway.

Configuration de l'application

Créer et compléter un fichier application.yaml à la racine du projet sur le modèle de application-sample.yaml

Des indications sont présentes dans le fichier pour aider à sa configuration.

Éléments de configuration importants

Property app.production

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.

En étant à false, cette property autorise également l'interception de tous les mails applicatifs.

Envoi de mail

Sur votre environnement de test/développement, pour empêcher l'envoi de mails de test en réel, il est conseillé :

  • d'utiliser un mail catcher (https://mailcatcher.me/) en remplacement de votre smtp
  • ou de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
    • app.production à false
    • spring.mail.intercept.active à true
    • et spring.mail.intercept.mails contenant une ou plusieurs adresses de réception des mails

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.

WebServices Apogée

Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.

Les properties différent du classique configUrlServices.properties de l'AMUE.

Des headers peuvent être ajoutés en paramètre de chaque WebService.

Exemple :

ws:
  apogee:
    administratif:
      url: https://api.univ.fr/apo/amue_apo_administratif
      headers:
#        header1: value1
#        header2: value2
      username: xxxx
      password: xxxx

Configurer et lancer le projet dans Eclipse

  • Importer le projet Maven dans eclipse.
  • Lorsque la configuration est terminée, démarrer l'application en faisant un clic droit sur fr.univlorraine.hypercerts.Application.java et en choisissant 'Run As / Java Application'.

Customisation des services

Plusieurs services sont personnalisables en fonction de votre environnement.

Sous fr.univlorraine.hypercerts.apogee.service.customs :

  • ApogeeUserServiceCustomExample
    • Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid LDAP
  • BlocageServiceCustomExample
    • Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
  • ComposanteServiceCustomExample
    • Personnalisation de la récupération :
      • de toutes les composantes
      • des composantes pour un utilisateur à partir de l'uid LDAP
      • du nombre de composantes pour un utilisateur à partir de l'uid LDAP

Pour personnaliser un de ces services :

  1. Copier la classe en la renommant
  2. Implémenter la ou les méthodes
    1. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement

  3. Dé-commenter les 2 annotations :1.

    @Service → Pour que Spring implémente le Service au démarrage

    1. et @Override** → Pour que l'implémentation surcharge le service par défaut

  4. Au démarrage de l'application
    1. Une ligne "Overriding XXX for YYY implementation" doit apparaître dans les logs

Exemple :

/**
 * Override default ApogeeUserService implementation.
 * >> README
 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUserService pour que l'implémentation soit utilisée.
 *
 * @author Matthieu Manginot
 */
@NoArgsConstructor
@Slf4j
@Service
@OverrideApogeeUserService
public class ApogeeUserServicePERSO implements IApogeeUserService {

@PersistenceContext(unitName = "apogeeEntityManagerFactory")
private EntityManager entityManagerApogee;

@PostConstruct
public void init() {
log.info("Overriding {} for IApogeeUserService implementation", getClass().getCanonicalName());
}

/**
 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUserService#getEmail(java.lang.String)
 */
@Override
public String getEmail(final String uidLdap) {
/* Implémentation personnalisée de getEmail. entityManagerApogee.createNativeQuery... */
return "mail@univ.fr";
}
}


Paramétrage de Digiposte

Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.

Tâches Maven

  • Lancer l'application (hors d'un IDE) :
mvn spring-boot:run
  • Lancer les tests :
mvn verify
  • Créer le package pour production :
mvn clean package -Pproduction

Makefile

Un Makefile est également disponible. A la racine, utilisez `make help` pour obtenir les commandes disponibles.

Tests d'intégration avec jeux de données

Pour s'assurez que les résultats d'admission de vos étudiants soient bien correctes, et afin d'éviter les faux positifs (donc envoyer une attestation de réussite à un•e étudiant•e non reçu•e aux examens), vous pouvez créer des tests unitaires avec vos propres jeux de données.

Les tests utilisent 3 classes:

  • ResultatsTests.java
  • ResultatsTestCase.java
  • ResultatsServiceTest.java

ResultatTests.java énumère tous les tests. Il utilise l'objet ResultatTestCase dans lequel on précise:

  • Le codEtu
  • L'année
  • Le diplôme
  • La VDI
  • Le résultat attendu (le test réussi si c'est ce résultat qui est trouvé dans ResultatService.java)

ResultatServiceTest.java est responsable du lancement des tests JUnit.

Ainsi, pour créer vos tests, ajoutez votre jeu de données dans ResultatTests, avec des résultats d'admissions réputés corrects et utilisez ResultatServiceTest pour tester les cas consécutivement.