01 - Documentation technique

Version 61.1 par Matthieu Manginot le 05/09/2022 - 14:45

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. 

Technologie

Version

JDK

11+

SpringBoot

2.3

Vaadin (Frontend)

14

Tomcat

9+

MariaDB

14+

Maven

3.6+

Connection Apogée


Connection LDAP


Téléchargement des sources

Installation d'Hypercerts

Initialisation / Mise à jour de la base

La base hypercerts MariaDB/MySQL s'initialise / se met à jour 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 de données hypercerts, 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 ou ci-dessous.

Maven / Exécution de l'application

  • Sous un IDE, exemple Eclipse, avec le fichier de configuration à la racine :
    • Clic droit sur "Application.java > Run As > Java Application"
  • Lancer l'application (hors d'un IDE), avec fichier de configuration à la racine :
mvn spring-boot:run
  • Lancer les tests :
mvn verify
  • Créer le package pour production :
mvn clean package -Pproduction
  • 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 :
export JAVA_OPTS="$JAVA_OPTS -Dspring.config.location=$HOMEDIR/application.yaml"

Configuration

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 la configuration de l'interception globale 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 globalement 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
    • Pour éviter l'envoi de mails Digiposte de test en réel, il conviendra de renseigner : spring.mail.intercept.mailDigiposte avec une adresse mail / liste

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.

Envoi des attestations aux étudiants

Les attestations peuvent être envoyées aux étudiants par mail et/ou sur Digiposte.

Pour activer l'envoi par mail, mettre la property app.useMailDelivery à true.

Pour activer l'envoi sur Digiposte, mettre la property app.usingDigiposteDelivery à true.

Il est possible de modifier le comportement par défaut de l'application au moment de la création des campagnes, en activant la property app.overrideDeliveryOnGeneration.

Ce qui affichera le choix suivant dans l'interface pour tous les gestionnaires :

image2021-3-19_12-1-4.png

WebServices Apogée

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

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

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

Exemple :

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

Customisation des templates de mail

Les properties suivantes servent à indiquer les templates personnalisés :

  • spring.mail.templateName.attestation : pour le mail à destination de l'étudiant contenant l'attestation 
  • spring.mail.templateName.creationDigiposte : pour le mail à destination de l'étudiant envoyé après la création du coffre Digiposte
  • spring.mail.templateName.creationCampagne : pour le mail d'une nouvelle campagne (à destination du gestionnaire qui a lancé la campagne)
  • spring.mail.templateName.reportCampagne : pour le mail de rapport de campagne (à destination du gestionnaire qui a lancé la campagne)

Par défaut, les valeurs sont vides et les templates par défaut de l'application sont utilisés

Pour customiser un template :

  • Copier et renommer un template HTML présent sous src/main/resources/templates
  • Par exemple pour le mail d'attestation :
    • Renommer mail-attestation.html en mail-attestation-custom.html
    • Adapter le template
    • Dans la config, saisir spring.mail.templateName.attestation : mail-attestation-custom.html

Customisation des services

Plusieurs services sont personnalisables en fonction de votre environnement.

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

  • ApogeeUtilisateurServiceCustomExample
    • Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid Apogée
  • ApogeeBlocageServiceCustomExample
    • Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
  • ApogeeComposanteServiceCustomExample
    • Personnalisation de la récupération :
      • de toutes les composantes 
        • → utilisé pour donner les droits sur toutes les composantes aux super admins
      • des composantes pour un utilisateur à partir de l'uid Apogée
      • du nombre de composantes pour un utilisateur à partir de l'uid Apogée
  • ApogeeUidServiceCustomExample
    • Personnalisation de la récupération de l'uid Apogée d'un utilisateur à partir de son 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 @OverrideXXX → 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
  5. Sans IDE, penser à ajouter les imports suivant :
    1. import org.springframework.stereotype.Service;
    2. import fr.univlorraine.hypercerts.apogee.services.annotations.OverrideXXX;

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

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

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

/**
 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUtilisateurService#getMail(java.lang.String)
 */
@Override
public String getMail(final String uidApogee) {
/* Implémentation personnalisée de getMail. entityManagerApogee.createNativeQuery... */
return null;
}
}

Configuration de Digiposte

Dans application.yaml sous digiposte.*

  • digiposte
    • codeDistributeur : Code distributeur Digiposte (fourni par Digiposte)
    • codeEmetteur : Code emetteur Digiposte (PID) (fourni par Digiposte)
    • type : Type de campagne : en mode OPT-IN = PREINSCRIPTION ou mode OPT-OUT = PREINSCRIPTION_WITH_VALIDATED_MEMBERSHIP (param Digiposte)
    • sendMailHypercerts : Envoi du mail Hypercerts pour informer l'étudiant qu'un coffre Digiposte est crée
    • docDigiposteEtudiant : Url de la documentation Digiposte pour les étudiants présente dans le mail d'information
    • sendMailDigiposte : Envoi du mail Digiposte : 'YES' ou 'NO' (param Digiposte)
    • checkMailMode : Vérification du mail : mail vérifié par l'émetteur = CHECKED ou mail non vérifié = INFORMATION (param Digiposte)
    • urlAccesDirect : Urls d'accès direct à Digiposte pour les adhésions ou les résiliations
      • adhesions : Url pour les adhésions directes
      • resiliations : Url pour les résiliations directes
    • adhesions : Configuration de l'envoi des adhésions (création des coffres)
      • ftp : Connexion au sftp Digiposte des adhésions 
      • ws : Connexion au ws Digiposte
    • routages : Configuration de l'envoi des routages (dépôt des attestations dans les coffres)
      • ftp : Connexion au sftp Digiposte des routages 
      • publisher : Configuration du publisher : Clé publique pour la sécurisation des routages

Egalement, pour éviter l'envoi de mails Digiposte de test en réel, il faudra activer l'interception globale des mails et renseigner : spring.mail.intercept.mailDigiposte avec une adresse mail / liste

Une fois configuré, il faudra activer Digiposte avec la property app.usingDigiposteDelivery : true

Réaliser un test réel en production

Pour par exemple valider Digiposte en production, il est possible d'intercepter les mails pour un ou plusieurs étudiants d'un diplôme. (Intercepter = Remplacement du mail de l'étudiant par celui configuré)

Si l'interception globale est activée, elle sera prioritaire sur celle-ci

Dans application.yaml sous spring.mail, il faudra décommenter les éléments suivant pour activer l'interception :

  • interceptEtudiants
    • codDiplome : A remplacer par le code diplôme à intercepter
      • "codEtudiant" :  A remplacer par le code étudiant à intercepter

Exemple :

spring:
  mail:
...
    interceptEtudiants:
      ABCDEF:
       "12345678": interceptMail@univ.fr

Un message d'avertissement sera affiché dans l'interface pour le diplôme concerné :

image2021-4-21_12-2-30.png

Administration

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

Gestion


Vue

Utilisation

image2021-2-23_10-42-24.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.

Loggers


Vue

Utilisation

image2021-2-23_10-42-53.png

Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application.

Utile pour par exemple afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.