Documentation technique

Version 26.1 par Matthieu Manginot le 02/12/2020 - 11:36

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	6.00.50
Connection LDAP

Téléchargement des sources

La dernière version des sources : hypercerts-1.0.3-SNAPSHOT.zip

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 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.

É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 la configuration de l'interception de tout 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 de mails ont en copie de cette property. Elle est optionnelle et 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 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

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 la classe 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 :

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 :

Copier la classe en la renommant
Implémenter la ou les méthodes
1. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
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
Au démarrage de l'application
1. Une ligne "Overriding XXX for YYY implementation" doit apparaître dans les logs
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;
}
}

Paramétrage de Digiposte

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

Il convient donc de laisser la property app.isUsingDigiposteDelivery à false.

Maven / Exécution de l'applicatoin

Sous un IDE, exemple Eclipse, avec fichier de config à la racine contenant les sources :
- Clic droit sur "Application.java > Run As > Java Application"
Lancer l'application (hors d'un IDE), avec fichier de config à la racine contenant les sources :

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"

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
	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.

Vue

Utilisation

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
	Cette vue permet de modifier à chaud sans re-démarrage le niveau de logs de tout les loggers de l'application. Utile pour afficher les requêtes SQL (filtre: sql) ou des logs plus précis en fonction des classes/packages.