01 - Documentation technique

• • Prérequis
  • Téléchargement des sources
  • Installation d'Hypercerts
    • Initialisation / Mise à jour de la base
    • Configuration de l'application
    • Maven / Exécution de l'application
  • Configuration
    • Property app.production
      • Envoi de mail
    • Envoi des attestations aux étudiants
    • WebServices Apogée
    • Customisation des templates de mail
    • Customisation des services
    • Configuration de Digiposte
    • Réaliser un test réel en production
  • Administration
    • Gestion
    • Loggers

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. 

Téléchargement des sources

• Pour WS Apogée 6.20.70 : hypercerts-1.0.5.8-SNAPSHOT.zip
• Précédentes versions : 
  • Pour WS Apogée 6.10.02 et plus : hypercerts-1.0.5.7-SNAPSHOT.zip
  • Pour les WS Apogée 6.10.00 : hypercerts-1.0.5.4-SNAPSHOT.zip

Installation d'Hypercerts

Initialisation / Mise à jour de la base

La base hypercerts MariaDB/MySQL s'initialise / se met à jour avec la commande Flyway suivante :

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

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 :

• Lancer les tests :

• Créer le package pour production :

• 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 :

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 :

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 :

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)

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;
      
      

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

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é)

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 :

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

Administration

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

Gestion

Loggers