Documentation technique

Version 11.1 par Matthieu Manginot le 23/07/2020 - 15:47

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

Après avoir créé une base de données "hypercerts", 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.

Administration

Les super admins ont accès à des vues supplémentaires. Des onglets pour ces dernières apparaissent dans le panneau de gauche.

image2020-7-23_12-41-56.png

Gestion


Vue

Utilisation

image2020-7-23_12-51-28.png

Cette vue permet de lancer les tâches qui s’exécutent automatiquement de façon manuelle.

Trigger CRON jobs permet de lancer toutes les tâches de dématérialisation jusqu'à ce qu'elles aboutissent toutes.

On peut aussi utiliser des boutons pour lancer plus finement des tâches.

À noter que si l'application n'est pas configurée pour utiliser Digiposte, les boutons sous Digiposte n'auront pas d'effet.