Documentation paramétrage emplois du temps

docs/DevAbsencesCalendrier.md

@@ -1,15 +1,6 @@
 # Absences et emplois du temps (développeurs)
 
-Les emplois du temps sont gérés par un autre logiciel, comme:
+Notes/idées pour les développeurs. WIP, en vrac.
-
-- Hyperplanning
-- Celcat
-- GPU
-- VT [Visual Timetabling](http://visual.timetabling.free.fr)
-- ...
-
-Ces logiciels peuvent exporter les calendriers au format ICS (iCalendar,
-[RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)).
 
 ## Calendriers et évènements
 
@@ -25,17 +16,6 @@ comporte:
 On suppose qu'on a un calendrier par "formation" (`FormSemestre` ScoDoc),
 identifié par un code (par exemple, code étape Apogée) que l'on appellera `edt_id`.
 
-### Fuseaux horaires
-
-La lecture de l'ics donne des dates avec time zone, en général en UTC.
-
-L'affichage se fait en heure locale du client.
-
-Problèmes:
-
-- les paramètres `assi_morning_time`, `assi_afternoon_time` semblent se référer
-  à l'heure serveur ?
-
 ### Exemple: cas de l'USPN
 
 Cet établissement utilise HyperPlanning. Les calendrier sont exportés

docs/EmploisDuTemps.md

@@ -1,22 +1,45 @@
 # Utilisation des emplois du temps
 
-ScoDoc peut être interfacé avec un logiciel de gestion des emplois du temps.
+ScoDoc peut être interfacé avec un logiciel de gestion des emplois du temps (EDT).
 Le paramétrage peut-être assez complexe, mais une fois mis en place cela permet
 à ScoDoc d'afficher l'emploi du temps des étudiants d'un semestre et facilite
 grandement la saisie des absences.
 
-TODO **document en cours de rédaction : passer par le Discord pour en savoir plus**
-
 ## Principes généraux
 
-principe général: ics, ...
+Les emplois du temps sont gérés par un autre logiciel, comme:
-TODO
 
-### Fichiers ics
+- Hyperplanning
+- Celcat
+- GPU
+- VT [Visual Timetabling](http://visual.timetabling.free.fr)
+- ...
 
-TODO
+Ces logiciels peuvent exporter les calendriers au format ICS (iCalendar,
+[RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)).
 
-### Fuseau horaire
+ScoDoc va lire ces calendriers (fichiers ics). Il doit y avoir un fichier
+calendrier par semestre ScoDoc, contenant tous les évènements (cours, TD, TP...)
+du semestre.
+
+### Fichiers calendrier ics
+
+Un calendrier est ici une liste d'évènements, chaque cours étant un évènement.
+L'évènement comporte:
+
+- dates début et fin;
+- identifiant du groupe d'étudiants concerné (dans la formation, par ex. groupe
+  de TD);
+- identifiant du module (enseignement): par exemple, l'élément Apogée.
+- identifiant de l'enseignant concerné.
+
+On suppose qu'on a un calendrier par "semestre" (`FormSemestre` ScoDoc),
+identifié par un code (par défaut, le premier code étape Apogée) que l'on
+appellera `edt_id`. Lors de la configuration, on indiquera à ScoDoc où sont
+placés ces fichiers.
+
+
+!!! note "Note: fuseau horaire"
 
     Les calendriers sont exportés avec des dates comportant l'indication du fuseau
     horaire. ScoDoc affiche en principe toutes les heures en *heure locale du
@@ -25,30 +48,143 @@ l'utilisateur qui peut être en déplacement dans un autre pays).
 
 ## Paramétrage global (administrateur)
 
-**par le super-admin: Indiquer comment paramétrer les regexp, avec un exemple VEVENT.**
+Le super-administrateur a accès à la page de configuration via le lien
+"**Configuration du suivi de l'assiduité et accès aux emplois du temps**".
 
-TODO
+La première chose à faire est d'indiquer où sont placés les fichiers calendrier.
+L'emploi du temps étant variable, ces fichiers vont en général être exportés à
+intervalles réguliers (par exemple chaque heure) et écrits dans un répertoire
+donné du serveur ScoDoc. ScoDoc ne se charge pas de cette tâche:
+l'administrateur système doit mettre en place un mécanisme d'export et de
+recopie ou partage des calendriers.
 
-## Identifiants: semestres, groupes, modules, enseignants
+Le chemin se configure ici:
 
-**indiquer où renseigner les identifiants (admin de dept) avec copies d'écran**
+![Configuration chemin vers le calendrier](screens/edt-config-chemin.png)
-TODO
+
+### Exemple d'évènement ics
+
+Exemple venant d'un établissement utilisant HyperPlanning. Les calendrier sont exportés
+régulièrement, on a un fichier ics par formation (code Apogée).
+
+```ics
+BEGIN:VEVENT
+CATEGORIES:HYPERPLANNING
+DTSTAMP:20231101T140300Z
+LAST-MODIFIED:20230905T094241Z
+UID:Cours-423101-5-BUT2_RT_pa._CYBER-Index-Education
+DTSTART:20230920T060000Z
+DTEND:20230920T083000Z
+SUMMARY;LANGUAGE=fr:TP2 GPR1 - VCYR303 - Services reseaux ava (VCYR303) - 1234 - M. VIENNET EMMANUEL - V2ROM - BUT2 RT pa. ROM - Groupe 1
+LOCATION;LANGUAGE=fr:P202 CRIT - P202 CRIT.RESEAUX
+DESCRIPTION;LANGUAGE=fr:Matière : VCYR303 - Services reseaux ava (VCYR303)\nEnseignant : 1234 - M. VIENNET EMMANUEL\nPromotion : V2ROM - BUT2 RT pa. ROM\nTD : Groupe 1\nSalle : P202 CRIT - P202 CRIT.RESEAUX\nMémo : TP2 GPR1\n
+X-ALT-DESC;FMTTYPE=text/html:Matière : VCYR303 - Services reseaux ava (VCYR303)<br/>Enseignant : 1234 - M. VIENNET EMMANUEL<br/>Promotion : V2ROM - BUT2 RT pa. ROM<br/>TD : Groupe 1<br/>Salle : P202 CRIT - P202 CRIT.RESEAUX<br/>Mémo : TP2 GPR1<br/>
+END:VEVENT
+```
+
+On a ici:
+
+- identifiant de la formation: dans le nom du fichier calendrier (ici `V2CYB.ics`);
+- identifiant du groupe: dans `SUMMARY`, `* - <groupe>`
+- identifiant du module: on a le code `VCYR303` à trois endroits: `SUMMARY`,
+  `DESCRIPTION`, `X-ALT-DESC`.
+- identifiant de l'enseignant: `SUMMARY`, `DESCRIPTION`, `X-ALT-DESC`.
+
+## Extraction des identifiants: semestres, groupes, modules, enseignants
+
+La page de configuration globale, accessible uniquement au super-admin, permet
+d'indiquer comment ScoDoc doit extraire les identifiants du calendrier:
+
+![Configuration des expressions régulières d'extraction](screens/edt-config-regexps.png)
+
+
+## Configuration des identifiants EDT dans ScoDoc
+
+On a vu plus haut comment ScoDoc extrayait les identifiants de groupes, modules
+et enseignants des évènements calendrier. Mais ces identifiants ne sont pas
+toujours les mêmes que ceux utilisés dans ScoDoc, par exemple parce que les deux
+logiciels n'ont pas été configurés par le même service ou à des moments
+différents. Ainsi, il arrive qu'un groupe soit nommé "TD A" dans l'emploi du
+temps et "TDA" dans ScoDoc.
+
+Chaque objet ScoDoc a donc un champs spécial "identifiant EDT" (pour *emploi du
+temps) que l'on peut renseigner.
 
 ### Semestres
 
-TODO
+L'identifiant `edt_id` (utilisé pour trouver le fichier calendrier) du semestre
+devra être renseigné pour chaque semestre sur la page `Semestre/Modifier le
+semestre`. À défaut, ScoDoc utilisera le premier code étape Apogée.
+
+![Configuration de l'edt_id](screens/edt-config-edt_id.png)
 
 ### Groupes d'étudiants
 
-TODO
+Les identifiants de groupe sont édités sur la page **Groupes / Modifier groupes
+et partitions**.
+
+Pour faciliter la mise en correspondance, la page d'aide à la configuration de
+l'emploi du temps (lien accessible sous le calendrier) permet de lister les
+identifiants de groupes utilisés de part et d'autre.
+
+Dans l'exemple ci-dessous, on voit que de nombreux évènements du calendrier ne sont
+pas associés à un groupe reconnu ("STAGE", "START CAMPUS", etc.). ScoDoc les
+attribuera automatiquement à l'ensemble de la promotion (groupe "tous").
+
+On voit aussi que les groupes ne sont pas reconnus car ils ne sont pas nommés de
+la même façon dans l'emploi du temps (ici généré par HyperPlanning) et dans
+ScoDoc: ainsi, le "TD A" de l'emploi du temps est nommé "TDA" dans ScoDoc.
+Nous indiquons ci-dessous comment corriger cela.
+
+![Exemple configuration groupes EDT](screens/edt-config-groupes-1.png)
+
+Pour modifier les identifiants EDT de groupe, on peut renommer les groupes
+ScoDoc ou, si on souhaite conserver les noms, indiquer le nom de l'emploi du
+temps. Passer par la page **Groupes / Modifier groupes et partitions**:
+
+![Modification des noms de groupes](screens/edt-edit-partitions-1.png)
+
+et cliquer sur le "crayon" d'édition du groupe, par exemple pour indiquer que le
+"TDA" de ScoDoc est appelé "TD A" dans l'emploi du temps:
+
+![Modification des noms de groupes](screens/edt-edit-partitions-2.png)
+
 
 ### Modules
 
-TODO
+ScoDoc peut utiliser plusieurs codes, dans cet ordre:
+
+1. identifiant EDT du module du semestre;
+2. code Apogée du module du semestre (renseigné si ce code est différent de
+   celui indiqué dans la formation, ce qui est rare);
+3. code Apogée du module dans la formation.
+
+Dans la plupart des cas, l'emploi du temps utilise le code Apogée et il n'y a
+aucune configuration à faire (si vous avez déjà renseigné les codes Apogée dans
+ScoDoc).
+
+Pour éditer les identifiants et codes Apogée du semestre, passer par la page
+**Modifier les codes Apogée et emploi du temps des modules**, lien placé sur la
+page **Semestre / Modifier le semestre**:
+
+![Configuration des codes modules](screens/edt-config-codes-modules.png)
 
 ### Enseignants
 
-TODO
+Les évènements de calendrier peuvent indiquer des enseignants (le chargé de
+cours, ...), ce qui permettra à ScoDoc de proposer à l'utilisateur les plages le
+concernant. L'identifiant est là aussi variable selon les logiciels et les
+établissements (il peut s'agir de l'adresse mail, d'un numéro, etc.).
+
+L'utilisateur ScoDoc a un identifiant EDT, que l'on peut spécifier sur la page
+d'édition du compte (avec les droits super-admin):
+![Config compte utilisateur](screens/edt-config-user.png)
+
+Cet identifiant peut aussi être extrait automatiquement des informations
+renvoyées par le CAS quand il est utilisé. Pour cela, indiquer l'expression
+d'extraction sur la page de configuration du service CAS.
+
+![Configuration extraction uid](screens/edt-config-cas-userid.png)
 
 ## Problèmes fréquents (FAQ)