ScoDoc/DocScoDoc
7
2
Fork 10
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity
007987db88
DocScoDoc/docs/ScoDoc9API.md

89 KiB
Raw Blame History

API pour ScoDoc 9

L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux informations aux formats XML et JSON.

La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification. Les clients de l'ancienne API ScoDoc 7 doivent être adaptés pour fonctionner avec ScoDoc 9.

Cette API est encore incomplète: n'hésitez pas à demander de nouveaux accès en écrivant à la liste de diffusion, ou sur le canal #API du Discord développeurs.

L'API fournit des données JSON, sauf exception (bulletins PDF par exemple).

Les objets ScoDoc manipulables sont identifiés par des id numériques.

  • etudid: étudiant
  • formation_id: un programme de formation (page "programmes");
  • ue_id: une UE dans un programme;
  • matiere_id: une matière dans un programme;
  • module_id: un module dans un programme;
  • moduleimpl_id: un module réalisé dans un semestre;
  • formsemestre_id: un "semestre" de formation.

(pour plus de précisions, voir la doc interne)

L'URL complète est de la forme: https://scodoc.example.com/ScoDoc/api/<fonction>. ( à choisir dans Référence)

Configuration de ScoDoc pour utiliser l'API

Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.

Les droits à accorder dépendent des fonctionnalités nécessaires. la permission ScoView est généralement suffisante car elle permet toutes les consultations. Cependant si, par l'API, on veut effectuer des opérations de modification ou encore consulter les comptes utilisateurs, d'autres droits (ScoChangeGroups, ScoUsersView, ScoSuperAdmin, ...) peuvent être requis. La consultation du tableau récapitulatif ou la ligne permissionde chaque entrée vous donnera la permission requise pour chaque opération.

En général, il est recommandé de créer un rôle, de lui attribuer les permissions que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle.

En ligne de commande, cela peut se faire comme suit (voir détail des commandes sur le guide de configuration).

# se connecter comme utilisateur scodoc
su - scodoc

# Créer un rôle
flask create-role LecteurAPI
# Lui donner les droits nécessaires: ici ScoView
flask edit-role LecteurAPI -a ScoView

# Créer un nouvel utilisateur avec ce rôle:
flask user-create lecteur_api LecteurAPI @all

# Ou bien, si on veut utiliser un compte existant:
#   associer notre rôle à un utilisateur
flask user-role lecteur_api -a LecteurAPI


# Au besoin, changer le mot de passe de l'utilisateur
# (on aura besoin de ce mot de passe dans la configuration du client d'API)
flask user-password lecteur_api
...

Si vous êtes intéressé par le développement, voir

!!! note

- Si vous utilisez le CAS, pensez à laisser les comptes utilisateurs API se
connecter via ScoDoc sans CAS. Pour cela, cocher l'option
*Autorise connexion via CAS si CAS est activé*
dans leur formulaire de configuration.

- Si l'utilisateur est associé à un département (cas des comptes créés via l'interface Web), 
il ne pourra accéder à l'API que via une *route départementale*, c'est à dire une route comprenant
l'acronyme de son département, de la forme `https://...//ScoDoc/DEPARTEMENT/api/...`.

Essais avec HTTPie

HTTPie est un client universel livre et gratuit très commode, disponible pour Windows, Linux, en ligne de commande ou interface graphique.

Exemple d'utilisation en ligne de commande et interroger votre ScoDoc pour obtenir la liste des départements:

http -a USER:PASSWORD POST  'http://localhost:5000/ScoDoc/api/tokens'

Qui affiche:

HTTP/1.1 200 OK
Content-Length: 50
Content-Type: application/json
Date: Thu, 05 May 2022 04:29:33 GMT

{
    "token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz"
}

(remplacer USER:PASSWORD par les identifiants de votre utilisateur et adapter l'URL qui est ici celle d'un client local sur le serveur de test).

Avec ce jeton (token), on peut interroger le serveur:

http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"

qui affiche par exemple:

HTTP/1.1 200 OK
Content-Length: 151
Content-Type: application/json
Date: Thu, 05 May 2022 05:21:33 GMT

[
    {
        "acronym": "TAPI",
        "date_creation": "Wed, 04 May 2022 21:09:25 GMT",
        "description": null,
        "id": 1,
        "visible": true
    }
]

Fonctions d'API ScoDoc 9

La documentation ci-dessous concerne la nouvelle API, disponible à partir de la version de ScoDoc 9.3.25.

Accès à l'API REST

L'API est accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/<fonction>, et aussi via les routes départementales de la forme https://scodoc.monsite.tld/ScoDoc/<dept_acronyme>/api/<fonction> pour un accès avec des droits restreints au département indiqué. La liste des <fonctions> est donnée ci-dessous dans Référence.

Authentification

Lors de votre authentification (connexion avec login et mdp) à Scodoc, il vous sera attribué un jeton (token jwt généré automatiquement) vous permettant d'utiliser l'api suivant les droits correspondant à votre session.

Pour obtenir le jeton, il faut un compte sur ScoDoc (user_nameet password). Les autorisations et rôles sont gérés exactement comme pour l'application.

Exemple avec curl (un outil en ligne de commande présent sur la plupart des systèmes, voir plus haut pour la même chose avec la commande http):

curl -u user_name:password --request POST  https://SERVEUR/ScoDoc/api/tokens

où SERVEUR est l'adresse (IP ou nom) de votre serveur. La réponse doit ressembler à ceci:

{
  "token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX"
}

Vous trouverez dans /opt/scodoc/tests/api/exemple-api-basic.py un exemple complet en python d'interrogation de l'API.

Codes HTTP

Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer que la requête a été traitée avec succès.

Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par le serveur ScoDoc.

  • 200 : OK.
  • 401 : Authentification nécessaire. (jeton non précisé ou invalide)
  • 403 : Action non autorisée pour l'utilisateur associé au jeton.
  • 404 : Adresse incorrecte, paramètre manquant ou invalide, ou objet inexistant.
  • 500 : Erreur inconnue côté serveur.

Règles générales

  • une route s'écrit comme une suite de noms et d'identifiants;
  • les noms token, departement, formation, formsemestre, groupe, etudiant, bulletin, absence, logo, programme, évaluation, resultat, decision désignent des types d'objets;
  • les noms (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query, create, delete, edit, order sont des actions;
  • les noms restants (ids, courants, long, ...) sont des options, les autres noms sont des options ou des actions;
  • le dernier nom apparaissant sur une route donne le type d'objet renvoyé. Ce nom peut apparaître au singulier ou au pluriel.
    • au singulier un seul objet est renvoyé, si aucun objet n'est trouvé, retourne un 404;
    • au pluriel une collection d'objets est renvoyée, si aucun objet n'est trouvé, retourne une collection vide.
  • un type d'objet au singulier est généralement suivi immédiatement de son identifiant (unique). Exception: pour un étudiant, on peut également utiliser le NIP ou l'INE (qui ne sont pas uniques dans la base car un étudiant de même INE/NIP peut passer par plusieurs départements).

Référence

La carte syntaxique vous permet de retrouver une entrée à partir de sa syntaxe (le ? amène sur la documentation associée).

Le tableau récapitulatif vous permet de rechercher une entrée à partir du résultat attendu.

Carte syntaxique

carte_syntaxique

Tableau récapitulatif des entrées de l'API

Ce tableau est trié selon le type des informations renvoyées:

  • un nom simple représente un seul objet de ce type;
  • suivi de +désigne une forme 'longue' d'objet de ce type;
  • suivi de * désigne une liste de 0, 1 ou plusieurs objets du type;
  • suivi de # désigne une liste d'entiers (les ids des objets du type);
  • suivi de : puis d'un nom en majuscule indique une requête (POST) qui modifie les données de ScoDoc.
Retour Remarque Méthode Navigation Permission
assiduite une assiduité GET assiduité ScoView
assiduite***** liste d'assiduités d'un étudiant GET assiduités ScoView
assiduite***** liste d'assiduités d'un formsemestre GET assiduités-formsemestre ScoView
assiduite**#** liste d'id d'assiduités justifiées par un justificatif GET justificatif-justifies ScoView
assiduite:CREATE création d'assiduité POST assiduite-create ScoAssiduiteChange
assiduite:EDIT édition d'assiduité POST assiduite-edit ScoAssiduiteChange
assiduite:DELETE suppression d'assiduité POST assiduite-delete ScoAssiduiteChange
justificatif un justificatif GET justificatif ScoView
justificatif***** liste de justificatif d'un étudiant GET justificatifs ScoView
justificatif:CREATE création de justificatif POST justificatif-create ScoJustifChange
justificatif:EDIT édition de justificatif POST justificatif-edit ScoJustifChange
justificatif:DELETE suppression de justificatif POST justificatif-delete ScoJustifChange
justificatif:IMPORT importation de fichier justificatif POST justificatif-import ScoJustifChange
justificatif:EXPORT exportation de fichier justificatif POST justificatif-export ScoJustifChange
justificatif:REMOVE suppression de fichier justificatif POST justificatif-remove ScoJustifChange
departement***** tous les depts GET departements
departement**#** tous les ids des depts GET departements-ids ScoView
departement recherche par id GET departement ScoView
departement recherche par acronyme GET departement ScoView
departement:CREATE création d'un département POST departement-create ScoSuperAdmin
departement:EDIT modification d'un département POST departement-edit ScoSuperAdmin
departement:DELETE suppression d'un département POST departement-delete ScoSuperAdmin
formation***** toutes les formations accessibles GET formations ScoView
formation**#** ids des formations accessibles GET formations-ids ScoView
formation une formation GET formation ScoView
export GET formation-export ScoView
export**+** GET formation-export_with_ids ScoView
referentiel_competences GET formation-referenciel_competences ScoView
formsemestre**#** GET departement-formsemestres_ids ScoView
formsemestre***** GET departement-formsemestres_courants ScoView
formsemestre***** GET formsemestre-query ScoView
formsemestre***** GET etudiant-formsemestres ScoView
formsemestre GET formsemestre ScoView
moduleimpl GET moduleimpl ScoView
partition***** GET formsemestre-partitions ScoView
partition GET partition ScoView
partition:CREATE POST formsemestre-partition-create ScoEtudChangeGroups
partition:EDIT POST partition-edit ScoEtudChangeGroups
partition:ACTION POST formsemestre-partitions-order ScoEtudChangeGroups
partition:DELETE POST partition-delete ScoEtudChangeGroups
partition:ACTION POST partition-remove_etudiant ScoEtudChangeGroups
group:CREATE POST partition-group-create ScoEtudChangeGroups
group:EDIT POST group-edit ScoEtudChangeGroups
group:ACTION POST partition-groups-order ScoEtudChangeGroups
group:DELETE POST group-delete ScoEtudChangeGroups
group* GET etudiant-formsemestre-groups ScoView
group:ACTION POST group-set_etudiant ScoEtudChangeGroups
group:ACTION POST group-remove_etudiant ScoEtudChangeGroups
etudiant***** recherche par etudid, nip ou ine GET etudiants-clef ScoView
etudiant***** les étudiants actuels GET etudiants-courant ScoView
etudiant***** étudiants dont le nom commence par GET etudiants-name ScoView
etudiant***** GET departement-etudiants ScoView
etudiant***** GET formsemestre-etudiants ScoView
etudiant***** GET formsemestre-etudiants-query ScoView
etudiant***** GET group-etudiants-query ScoView
etudiant***** GET group-etudiants-query
etudiant GET etudiant ScoView
bulletin***** GET formsemestre-bulletin ScoView
bulletin GET etudiant-formsemestre-bulletin ScoView
programme GET formsemestre-programme ScoView
GET formsemestre-etat_evals ScoView
GET formsemestre-resultats ScoView
jury GET formsemestre-decisions_jury ScoView
note* GET evaluation-notes ScoView
GET evaluation-notes-set (contextuelle)
logo***** GET logos ScoSuperAdmin
logo***** GET departement-logos ScoSuperAdmin
logo GET logo ScoSuperAdmin
logo GET departement-logo ScoSuperAdmin
user GET user ScoUsView
user***** GET users-query ScoUsView
user:CREATE POST user-create ScoUserAdmin
user:EDIT POST user-edit ScoUserAdmin
user:PASSWORD change le mot de passe d'un utilisateur POST user-password ScoUserAdmin
user:ACTION POST user-role-add ScoUserAdmin
user:ACTION POST user-role-remove ScoUserAdmin
permission***** GET permissions ScoUsView
role***** GET roles ScoUsView
role***** GET role ScoUsView
role:ACTION POST role-add_permission ScoUserAdmin
role:ACTION POST role-remove_permission ScoUserAdmin
role:CREATE POST role-create ScoUserAdmin
role:EDIT POST role-edit ScoUserAdmin
role:DELETE POST role-delete ScoUserAdmin

Note sur les exemples d'utilisation

Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-traitements non réalisés par l'API. Il n'est par exemple pas garanti que les clés des objets json sont triées:

  • les clés sont triées
  • les listes de plus de 2 éléments sont tronquées à 2 éléments, la fin de la liste étant représentée par la notation en json '...'
  • les dates (au format ISO) sont systématiquement remplacées par une date fixe (la date de modification d'un mot de passe peut évidement être différente de sa date de création)

API Départements

Structure Département

attribut type commentaire
acronym string acronyme du département (fixe et unique)
date_creation string date ISO
dept_name string Nom complet du département
descripton string
id int identifiant unique
visible bool affiché ou non dans la page d'accueil

departements

  • Méthode: GET
  • Routes: /departements
  • Exemple d'utilisation: /api/departements
  • Résultat: Liste de tous les départements (visibles ou non).
  • Exemple de résultat: departements.json

departements-ids

  • Méthode: GET
  • Permission: ScoView
  • Routes: /departements_ids
  • Résultat: Liste des id départements (visibles ou non).
  • Exemple de résultat:
  • Exemple de résultat: departements-ids.json

departement

  • Méthode: GET
  • Permission: ScoView
  • Routes:
    • /departement/id/<int:dept_id>
    • /departement/<string:dept>
  • Résultat: Un département
  • Exemple de résultat: departement.json

departement-create

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Paramètres: aucun
  • Data: { "acronym": str, "visible":bool }
  • Routes: /departement/create
  • Exemple d'utilisation: /departement/create

{ "acronym": "QLIO", "visible": true }

  • Résultat: Crée un nouveau département. L'acronyme du département (RT, GEII, ...) doit être unique (il est d'usage de le mettre en majuscules, mais ce n'est pas obligatoire). Le paramètre optionnel visibleindique si le département est affiché sur la page d'accueil de ScoDoc. Notez qu'un département "invisible" peut quand même être utilisé si l'on connait son adresse (URL). Renvoie le département créé.
  • Exemple de résultat: departements-create.json

departement-edit

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Paramètres: dept_acronym
  • Data: { "visible":bool }
  • Routes: /departement/<string:dept_acronym>/edit
  • Exemple d'utilisation: /departement/edit

{ "visible": false }

  • Résultat: Modifie un département. Seul le champs visible peut être modifié. L'acronyme ne peut pas être changé car il peut être mentionné dans de nombreux objets et documents, y compris à l'extérieur de ScoDoc.
  • Exemple de résultat: departements-edit.json

departement-delete

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Paramètres: dept_acronym
  • Routes: /departement/<string:dept_acronym>/delete
  • Exemple d'utilisation: /departement/delete/EARTH
  • Résultat: supprime définitivement un département. Toutes les données sont effacées (étudiants, formations, ...).
  • Exemple de résultat: departements-delete.json

API Etudiant

Structure Etudiant

attribut type commentaire
civilite string 'M', 'F' ou 'X' [1]
civilite_etat_civil string 'M', 'F' ou 'X' [1]
code_ine string non unique!
code_nip string non unique!
dept_id string id du département scodoc
id int id unique
nom string en majuscule [1]
nom_usuel string null si absent [1]
prenom string [1]
prenom_etat_civil string (si prenom d'usage <> etat_civil [1])
sort_key [ string, string ] nom-prenom pour trier
Format long
admission admission
adresses adresse
boursier bool
date_naissance string date ISO
dept_acronym string
dept_naissance string département du lieu de naissance
lieu_naissance string lieu de naissance (ville)
nationalite string
photo_filename string
scodoc7_id string de la forme 'EID9999'
statut string 'I', 'D' ou 'X'
Structure adresse
attribut type commentaire
codepostaldomicile string
description string
domicile string
email string
emailperso string
etudid string
fax string
id string
paysdomicile string
telephone string
telephonemobile string
typeadresse string
villedomicile string

etudiants-courants

  • Méthode: GET
  • Permission: ScoView
  • Routes:
    • /etudiants/courants
    • /etudiants/courants/long
  • Exemple d'utilisation: /api/etudiants/courants
  • Résultat: Liste des étudiants inscrits dans un formsemestre actuellement en cours. Avec /long, donne tous les attributs de l'étudiants (plus lent).
  • Exemple de résultat: etudiants-courants.json

etudiants-clef

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid, nip, ine
  • Routes: /etudiants/etudid/<int:etudid> ou /etudiants/nip/<string:nip> ou /etudiants/ine/<string:ine>
  • Exemple d'utilisation: /api/etudiants/nip/1
  • Résultat: Infos sur le ou les étudiants correspondants. Comme /etudiant mais renvoie toujours une liste. Si non trouvé, liste vide, pas d'erreur. Dans 99% des cas, la liste contient un seul étudiant, mais si l'étudiant a été inscrit dans plusieurs départements, on a plusieurs objets (1 par dept.).
  • Exemple de résultat: etudiants-clef.json

etudiants-name

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: name
  • Routes: /etudiants/name/<string:name>
  • Exemple d'utilisation: /api/etudiants/name/dup
  • Résultat: Liste ordonnée par nom d'étudiants dont le nom commence par name. Si nameest trop court (2 caractères), liste vide. La casse et les accents ne sont pas pris en compte dans la recherche.
  • Note: Cette fonction est utilisée pour la complétion des champs de formulaire (choix d'un étudiant).

departement-etudiants

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: dept, dept_id
  • Routes:
    • /departement/id/<int:dept_id>/etudiants
    • /departement/<string:dept>/etudiants
  • Exemple d'utilisation: /api/departement/MMI/etudiants
  • Résultat: liste tous les étudiants (passés ou présents) d'un département. On peut spécifier l'acronyme du département ("MMI") ou son id (un entier). Attention, la liste peut être longue: requête coûteuse à éviter.
  • Exemple de résultat: departement-etudiants.json

formsemestre-etudiants[-long][-query]

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formsemestre_id
  • Query string: etat ('I', 'D' ou 'DEF')
  • Routes:
    • /formsemestre/<int:formsemestre_id>/etudiants
    • /formsemestre/<int:formsemestre_id>/etudiants/query?etat=I,D,DEF
    • /formsemestre/<int:formsemestre_id>/etudiants/long
    • /formsemestre/<int:formsemestre_id>/etudiants/long/query?etat=I,D,DEF
  • Exemple d'utilisation:
    • /api/formsemestre/1/etudiants/long
    • /api/formsemestre/1/etudiants/query?etat=D
  • Résultat: Etudiants d'un formsemestre spécifié par son id. Une clé (sort_key) reproduit [ nom, prenom ] sous forme ASCII, permettant le tri des étudiants. Avec query, La liste est restreinte aux étudiants inscrits (I), démissionnaires (D) ou défaillants (DEF) si l'état est indiqué. Avec long, ajoute la date de naissance entre autre
  • Exemple de résultat:

group-etudiants[-query]

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: group_id
  • Query string: etat ('I', 'D' ou 'DEF')
  • Routes:
    • /group/<int:group_id>/etudiants
    • /group/<int:group_id>/etudiants/query
  • Exemple d'utilisation:
    • /ScoDoc/api/group/1/etudiants
    • /ScoDoc/api/group/1/etudiants/query?etat=I
  • Résultat: Etudiants d'un groupe spécifié par son id. Liste restreinte aux étudiants inscrits (I), démissionnaires (D) ou défaillants (DEF) si l'état est indiqué.
  • Exemple de résultat:

etudiant

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid, nip, ine
  • Routes:
    • /etudiant/etudid/<int:etudid> ou
    • /etudiant/nip/<string:nip> ou
    • /etudiant/ine/<string:ine>
  • Exemple d'utilisation: /api/etudiant/nip/1
  • Résultat: Retourne les informations sur l'étudiant correspondant à l'id passé en paramètres. Les codes INE et NIP sont uniques au sein d'un département. Si plusieurs objets étudiant ont le même code, on renvoie le plus récemment inscrit.
  • Pour obtenir tous les étudiants répondant au critère, utiliser etudiant-clefs
  • Exemple de résultat: etudiant.json

API Formation

Structure Formation

attribut type commentaire
acronyme string
code_specialité string
departement Département pour /formations mais pas pour /formation ?
dept_id int redondant avec departement.id ?
formation_code string défini la compatibilité avec d'autres formations
formation_id redondant avec id ?
id int id unique de formation
referentiel_competence_id int null si pas de référentiel associé
titre string URL encoded ?
titre_officiel string
type_parcours int
version int

formations

  • Méthode: GET
  • Permission: ScoView
  • Routes: /formations
  • Exemple d'utilisation: /ScoDoc/api/formations
  • Résultat: Liste de toutes les formations (tous départements accessibles).
  • Exemple de résultat: formations.json

formations_ids

  • Méthode: GET
  • Permission: ScoView
  • Routes: /formations_ids
  • Exemple d'utilisation: /ScoDoc/api/formations_ids
  • Résultat: Liste des ids de toutes les formations (tous départements accessibles).
  • Exemple de résultat: formations_ids.json

formation

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formation_id
  • Routes: /formation/<int:formation_id>
  • Exemple d'utilisation: /ScoDoc/api/formation/1
  • Résultat: Description de la formation.
  • Exemple de résultat: formation.json

API Formsemestre

Les sessions de formation (qu'elles durent une année ou un mois) sont représentées par les formsemestre.

Note sur les identifiants de formsemestre

Le session_id peut être utilisé pour identifier de façon prévisible et (presque) unique un formsemestre dans un établissement, ce qui est utile notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois du temps ou de services d'enseignement). Cet identifiant est constitué des informations suivantes:

  • Département (RT, GEII, INFO...) (acronyme en majuscules)
  • Nom parcours: BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
  • Modalité: FI, FC, FA
  • "Spécialité": S1 (ou S1D pour les semestres décalés), ou le code_specialite si pas de semestres. Le code spécialité est un champ (libre) dans la "formation" (le programme pédagogique).
  • Année: année de début de l'année scolaire correspondante (2014 pour une session appartenant à l'année scolaire 2014-2015, même si elle commence en mars 2015).

Exemple: INFO-DUT-FI-S1-2014 équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI).

Structure Formsemestre

attribut type commentaire
annee_scolaire int
block_moyenne_generale bool
block_moyennes bool inhibe le calcul des moyennes
bul_bgcolor string Couleur (CSS) de fond du bulletin
bul_hide_xml bool
date_debut date
date_debut_iso string
date_fin date
date_fin_iso string
departement Département
dept_id int
elt_annee_apo ???
elt_sem_apo string
ens_can_edit_eval bool
etape_apo string
etat bool
formation Formation
formation_id int
formsemestre_id int identification unique
gestion_compensation bool
gestion_semestrielles bool
id int id unique
modalite string "FI", "FA", ...
parcours ????
resp_can_change_ens bool
resp_can_edit bool
responsables int* liste des ids des enseignants responsables
scodoc7_id int
semestre_id int rang du semestre 1, ...
session_id string cf. Note sur les identifiants de formsemestre
titre string
titre_court string
titre_num string

departement-formsemestres_ids

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: dept
  • Routes:
    • /departement/id/<int:dept_id>/formsemestres_ids
    • /departement/<string:dept>/formsemestres_ids
  • Exemple d'utilisation: /api/departement/MMI/formsemestres_ids
  • Résultat: Liste des id des formsemestres (passés ou présents) d'un département donné.
  • Exemple de résultat: departement-formsemestres_ids.json

departement-formsemestres_courants

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: dept_id
  • Routes:
    • /departement/id/<int:dept_id>/formsemestres_courants
    • /departement/<string:dept>/formsemestres_courants
  • Exemple d'utilisation: /api/departement/MMI/formsemestres_courants
  • Résultat: Liste des formsemestres en cours d'un département donné.
  • Exemple de résultat: departement-formsemestres-courants.json

formsemestres-query

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: aucun
  • Query string: annee_scolaire, dept_acronym, dept_id, etape_apo, ine, nip
  • Route: /formsemestres/query
  • Exemple d'utilisation: /api/formsemestres/query?etape_apo=V7HU1&annee_scolaire=2021
  • Résultat: Description de formsemestres. Si plusieurs paramètres sont donnés, c'est la conjonction (ET) des critères qui est recherchée. Si aucun formsemestre ne satisfait la requête, une liste vide est retournée. Si ineou nipsont spécifiés, cherche les formsemestres dans lesquels un étudiant de ce code est inscrit.
  • Exemple de résultat: formsemestres-query.json

etudiant-formsemestres

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid, nip, ine
  • Routes:
    • /etudiant/etudid/<int:etudid>/formsemestres ou
    • /etudiant/nip/<string:nip>/formsemestres ou
    • /etudiant/ine/<string:ine>/formsemestres
  • Exemple d'utilisation: /etudiant/ine/1/formsemestres
  • Résultat: Liste des semestres qu'un étudiant a suivi, triés par ordre chronologique.
  • Exemple de résultat: etudiant-formsemestres.json

formsemestre

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formsemestre_id
  • Route: /formsemestre/<int:formsemestre_id>
  • Exemple d'utilisation: /api/formsemestre/1
  • Résultat: Description du formsemestre.
  • Exemple de résultat: formsemestre.json

API Groupe

partition-group-create

  • Méthode: POST
  • Permission: ScoEtudChangeGroups
  • Paramètres: partition_id
  • Data: { group_name : <string> }
  • Routes: /partition/<int:partition_id>/create
  • Exemple d'utilisation: /ScoDoc/api/partition/1962/create

{ "group_name" : "A" }

group-edit

  • Méthode: POST
  • Permission: ScoEtudChangeGroups
  • Paramètres: group_id
  • Data: { group_name : <string> }
  • Routes: /group/<int:group_id>/edit
  • Exemple d'utilisation: /ScoDoc/api/group/4581/edit

{ "group_name" : "nouveau" }

partition-groups-order

  • Méthode: POST
  • Permission: ScoEtudChangeGroups
  • Paramètres: partition_id
  • Data: [ <int:group_id1>, <int:group_id2>, ... ]
  • Routes: /partition/<int:partition_id>/groups/order
  • Exemple d'utilisation: /ScoDoc/api/partition/1962/groups/order

[ 4383, 4379, 4380, 4381, 4382, 4384 ]

group-delete

  • Méthode: POST
  • Permission: ScoEtudChangeGroups
  • Paramètres: group_id
  • Routes: /group/<int:group_id>/delete
  • Exemple d'utilisation: /ScoDoc/api/group/4581/delete
  • Résultat: Supprime un groupe.
  • Exemple de résultat: group-delete.json

etudiant-formsemestre-groups

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formsemestre_id, etudid, nip, ine
  • Routes: /etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups ou /etudiant/nip/<string:nip>/semestre/<int:formsemestre_id>/groups ou /etudiant/ine/<string:ine>/semestre/<int:formsemestre_id>/groups
  • Exemple d'utilisation: /etudiant/nip/1/semestre/1/groups
  • Résultat: Retourne la liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. (json)
  • Exemple de résultat: etudiant-formsemestres-groups.json

group-set_etudiant

  • Méthode: POST
  • Permission: ScoEtudChangeGroups
  • Paramètres: group_id, etudid
  • Routes: /group/<int:group_id>/set_etudiant/<int:etudid>
  • Exemple d'utilisation: /ScoDoc/api/group/4085/set_etudiant/12108
  • Résultat: Affecte un étudiant dans un groupe.
  • Exemple de résultat: groupes-set_etudiant.json

group-remove_etudiant

  • Méthode: POST
  • Permission: ScoEtudChangeGroups
  • Paramètres: group_id, etudid
  • Routes: /group/<int:group_id>/remove_etudiant/<int:etudid>
  • Exemple d'utilisation: /ScoDoc/api/group/4085/remove_etudiant/12108
  • Résultat: Retire un étudiant d'un groupe.
  • Exemple de résultat: groupes-remove_etudiant.json

API Jury

formsemestre-decisions_jury

  • Permission: ScoView
  • Méthode: GET
  • Paramètres: formsemestre_id
  • Routes: /formsemestre/<int:formsemestre_id>/decisions_jury
  • Exemple d'utilisation: /ScoDoc/api/formsemestre/1/jury
  • Résultat: Retourne le récapitulatif des décisions jury
  • Exemple de résultat: formsemestre-decisions_jury.json `

API Moduleimpl

Structure ModuleImpl

Le moduleimpl est la mise en place d'un module dans un formsemestre (avec son responsable et ses enseignants). La liste des moduleimpl d'un formsemestre peut être obtenu par l'entrée formsemestre-programme

attribut type commentaire
computation_expr string unused
ens User# liste des ids des enseignants du moduleimpl
formsemestre_id int id du formsemestre
id int identifiant unique
module Module
module_id int id du module
moduleimpl_id int **redondance id?
responsable_id int id du responsable de module

moduleimpl

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: moduleimpl_id
  • Routes: /moduleimpl/<int:moduleimpl_id>
  • Exemple d'utilisation: /ScoDoc/api/moduleimpl/1
  • Résultat: Description du moduleimpl.
  • Exemple de résultat: moduleimpl.json

API Partition

Structure Partition

L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieurs partitions (types de groupes). Chaque partition est constituée d'un nombre quelconque de groupes d'étudiants.

attribut type commentaire
bul_show_rank affichage sur bulletin
formsemestre_id int formsemestre hôte
groups Group* liste des groupes de la partition
groups_editable bool verrou (liste des groupes)
id int identifiant unique
numero int
partition_name string nom de la partition
show_in_lists bool

formsemestre-partitions

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formsemestre_id
  • Routes: /formsemestre/<int:formsemestre_id>/partitions
  • Exemple d'utilisation: /ScoDoc/api/formsemestre/911/partitions
  • Résultat: Liste de toutes les partitions d'un formsemestre.
  • Exemple de résultat: formsemestre-partitions.json

partition

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: partition_id
  • Routes: /partition/<int:partition_id>
  • Exemple d'utilisation: /ScoDoc/api/partition/1963
  • Résultat: Description d'une partition (y compris la liste de ses groupes).
  • Exemple de résultat: partition.json

formsemestre-partition-create

  • Méthode: POST
  • Permission: ScoEtudsChangeGroups
  • Paramètres: formsemestre_id
  • Data: { "partition_name" : <string> }
  • Routes: /formsemestre/<int:formsemestre_id>/partition/create

{ "partition_name" : "PART" }

  • Exemple d'utilisation: /ScoDoc/api/formsemestre/944/partition/create
  • Résultat: Crée une nouvelle partition dans un formsemestre.
  • Exemple de résultat: formsemestre-partition-create.json

partition-edit

  • Méthode: POST
  • Permission: ScoEtudsChangeGroups
  • Paramètres: partition_id
  • Data: { partition_name : <string> }
  • Routes: /partition/<int:partition_id>/edit
  • Exemple d'utilisation: /ScoDoc/api/partition/2047/edit

{ "partition_name" : "PART4" }

formsemestre-partitions-order

  • Méthode: POST
  • Permission: ScoEtudsChangeGroups
  • Paramètres: formsemestre_id
  • Data: [ <int:partition_id1>, <int:partition_id2>, ... ]
  • Routes: /formsemestre/<int:formsemestre_id>/partitions/order
  • Exemple d'utilisation: /ScoDoc/api/formsemestre/944/partitions/order

[ 2048, 2054 ]

partition-delete

  • Méthode: POST
  • Permission: ScoEtudsChangeGroups
  • Paramètres: partition_id
  • Routes: /partition/<int:partition_id>/delete
  • Exemple d'utilisation: /ScoDoc/api/partition/2047/delete
  • Résultat: Supprime une partition.
  • Exemple de résultat: partition-delete.json

partition-remove_etudiant

  • Méthode: POST
  • Permission: ScoEtudsChangeGroups
  • Permission: ScoEtudChangeGroups
  • Paramètres: partition_id
  • Routes: /partition/<int:partition_id>/remove_etudiant/<int:etudid>
  • Exemple d'utilisation: /ScoDoc/api/partition/1962/remove_etudiant/12107
  • Résultat: Retire un étudiant des groupes de la partition.
  • Exemple de résultat: partition-remove_etudiant.json

API Role

Les rôles ont un nom et sont associés à un ensemble de permissions. Un utilisateur pourra être associé à un ou plusieurs rôles dans chaque département (ainsi, il ou elle peut enseigner dans un département et être administrateur d'un autre).

roles

  • Méthode: GET
  • Permission: ScoUsersView
  • Routes: /roles
  • Exemple d'utilisation: /roles
  • Résultat: Liste de tous les rôles.
  • Exemple de résultat: roles.json

role

  • Méthode: GET
  • Permission: ScoUsersView
  • Routes: /role/<str:role_name>
  • Exemple d'utilisation: /role/Ens
  • Résultat: Liste le rôle indiqué. 404 si inexistant.
  • Exemple de résultat: role.json

role-add_permission

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Routes: /role/<str:role_name>/add_permission/<str:perm_name>
  • Exemple d'utilisation: /role/Ens/add_permission/ScoView
  • Résultat: Ajoute la permission au rôle. 404 si l'un des deux n'existe pas. Note: la liste des permissions est donnée sur ConfigPermissions.
  • Exemple de résultat: role-add_permission.json

role-remove_permission

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Routes: /role/<str:role_name>/remove_permission/<str:perm_name>
  • Exemple d'utilisation: /role/Ens/remove_permission/ScoView
  • Résultat: Retire la permission au rôle. 404 si l'un des deux n'existe pas. Si le rôle n'a pas la permission, ne fait rien.
  • Exemple de résultat: role-remove_permission.json

role-create

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Data: { "permissions" : [ permission, ... ] }
  • Routes: /role/create/<str:role_name>
  • Exemple d'utilisation: /role/create/LaveurDecarreaux

{ "permissions" : [ 'ScoView', 'ScoUsersView' ] }

  • Résultat: Crée un nouveau rôle, avec les permissions indiquées.
  • Exemple de résultat: role-create.json

role-delete

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Routes: /role/<str:role_name>/delete
  • Exemple d'utilisation: /role/LaveurDeCarreaux/delete
  • Résultat: Supprime ce rôle.
  • Exemple de résultat: role-delete.json

role-edit

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Data: { "permissions" : [ permission, ... ] }
  • Routes: /role/edit/<str:role_name>
  • Exemple d'utilisation: /role/create/LaveurDecarreaux

{ "name" : "LaveurDeVitres", "permissions" : [ 'ScoView' ] }

  • Résultat: Modifie le rôle: son nom et/ou ses permissions.
  • Exemple de résultat: role-edit.json

API User, Permissions

user

  • Méthode: GET
  • Permission: ScoUsersView
  • Paramètres: user_id
  • Route: /user/<int:user_id>
  • Exemple d'utilisation: /api/user/1
  • Résultat: Retourne la description d'un utilisateur.
  • Exemple de résultat: user.json

user-create

  • Méthode: POST
  • Permission: ScoUsersAdmin
  • Data:
{
        "user_name": str,
        "dept": str or null,
        "nom": str,
        "prenom": str,
        "active":bool (default True)
}
  • Routes: /user/create
  • Résultat: Crée un nouvel utilisateur. user_nameest le login, unique et non modifiable. L'utilisateur est normalement rattaché à un département, sauf si est "super-administrateur".
  • Exemple de résultat: user-create.json

users-query

  • Méthode: GET

  • Permission: ScoUsersView

  • Routes:

    • /users/query?departement=dept_acronym&active=1&starts_with=<str:nom>

  • Résultat: Liste d'utilisateurs, filtrés par département, statut, début de nom (paramètres tous optionnels). Seuls les utilisateurs que l'on a la permission de voir sont listés.

  • Exemple de résultat: users-query.json

user-edit

  • Méthode: POST
  • Permission: ScoUsersAdmin
  • Data:
{
        "dept": str or null,
        "nom": str,
        "prenom": str,
        "active":bool (default True)
}
  • Routes: /user/<int:uid>/edit
  • Résultat: Modifie l'utilisateur d'UID indiqué.
  • Exemple de résultat: user-edit.json

user-password

  • Méthode: POST
  • Permission: ScoUsersAdmin
  • Data: { "password": str }
  • Routes: /user/<int:uid>/password
  • Exemple d'utilisation: /user/3/password

`{ "password": "averycomplicatedpassaword" }

  • Résultat: Modifie le mot de passe de l'utilisateur désigné par son UID. L'opération peut être rejetée si le mot de passe ne satisfait pas les conditions requises (trop simple par exemple), avec le retour suivant:


{
    "error": "Bad Request",
    "status": 400,
    "message": "user_password: invalid password"
}
```

user-role-add

  • Méthode: POST
  • Permission: ScoSuperAdmin
  • Routes: /user/<int:uid>/role/<str:role_name>/add[/departement/<string:dept_acronym>]
  • Résultat: Attribue le rôle à l'utilisateur, dans le département indiqué (ou tous si le département n'est pas spécifié).)
  • Exemple de résultat: user-role-add.json

user-role-remove

  • Méthode: POST
  • Permission: ScoUsersAdmin
  • Routes: /user/<int:uid>/role/<str:role_name>/remove[/departement/<string:dept_acronym>]
  • Résultat: Retire le rôle à l'utilisateur.
  • Exemple de résultat: user-role-remove.json

permissions

  • Méthode: GET
  • Permission: ScoUsersView
  • Routes: /permissions
  • Résultat: Liste des noms des permissions. Ces permissions ne sont pas modifiables, mais de nouvelles peuvent apparaitre lors des mises à jour du logiciel. Voir ConfigPermissions.
  • Exemple de résultat: permissions.json

API Bulletin, Évaluations, Notes

Attention, les bulletins ne sont publiés sur l'API que si l'option "publier le bulletin sur le portail étudiant" est cochée dans le semestre concerné.

formsemestre-bulletins

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formsemestre_id
  • Route: /formsemestre/<int:formsemestre_id>/bulletins[/<string:version>]
  • Exemple d'utilisation: /api/formsemestre/1/bulletins
  • Résultat: Bulletins d'un formsemestre spécifié par son id.
  • Exemple de résultat: formsemestre-bulletins.json

Pour les formations classiques (toutes sauf BUT), les bulletins JSON peut ou non indiquer les matières. Par défaut (version long), il est structuré en UEs / modules. Si la version est short_matou long_mat, il sera structuré en UEs / matieres / modules.

etudiant-formsemestre-bulletin

Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules pour un formsemestre spécifié par son id. Par défaut les valeurs numériques sont formatées en chaînes. Si format=raw, valeurs numériques mais pas JSON compliant à cause des NaN.

  • Méthode: GET

  • Permission: ScoView

  • Paramètres: formsemestre_id, etudid, nip, ine

  • Query string: format

  • Routes: /etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin[/<string:version>][/pdf][/pdf/nosig] ou /etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin[/<string:version>][/pdf][/pdf/nosig] ou /etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin[/<string:version>][/pdf][/pdf/nosig]

  • Exemple d'utilisation: /etudiant/nip/1/formsemestre/1/bulletin

  • Résultat: Bulletin de l'étudiant dans le formsemestre. Deux variantes possibles:

    • versions long et short (long par défaut, ajoutez /short pour la version plus courte).
    • version json et pdf (json par défaut, ajoutez /pdf pour la version pdf)

    Pour les formations classiques (toutes sauf BUT), les bulletins JSON peut ou non indiquer les matières. Par défaut (version long), il est structuré en UEs / modules. Si la version est short_matou long_mat, il sera structuré en UEs / matieres / modules. Les notes moyennes de matières ne sont calculées que si l'option "Afficher les matières sur les bulletins" est activée pour le formsemestre considéré (sinon, la note vaut toujours "nd"). `

    Les versions PDF sont par défaut identiques à celles servies dans ScoDoc. Avec l'option /pdf/nosig, les signatures en fin de bulletin sont omises.

    Attention, les bulletins ne sont publiés sur l'API que si l'option "publier le bulletin sur le portail étudiant" est cochée dans le semestre concerné.

  • Exemple de résultat: etudiant-formsemestre-bulletin.json

formsemestre-programme

  • Méthode: GET

  • Permission: ScoView

  • Paramètres: dept, formsemestre_id

  • Routes: /formsemestre/<int:formsemestre_id>/programme

  • Exemple d'utilisation: /ScoDoc/api/formsemestre/1/programme

  • Résultat: Retourne la structure d'un formsemestre sous 5 entrées d'un dictionnaire:

    • ues: liste des UEs,
    • ressources: liste des ressources (BUT),
    • saes: liste des saes (BUT),
    • modules: liste des modules classiques (DUT ou sport/culture)
    • malus: listes des modules de type bonus/malus.

  • Exemple de résultat: formsemestre-programme.json

formsemestre-resultats

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formsemestre_id
  • Query string: format
  • Route: /formsemestres/resultats
  • Exemple d'utilisation: /api/formsemestre/1/resultats
  • Résultat: formsemestre-resultats.json

Récapitulatif par étudiant (état, groupe(s), moyennes d'UEs et de modules pour un formsemestre spécifié par son id. Par défaut les valeurs numériques sont formatées en chaînes. Si format=raw, valeurs numériques mais pas JSON compliant à cause des NaN.

  • Exemple de résultat:

moduleimpl-evaluations

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: moduleimpl_id
  • Routes: /moduleimpl/<int:moduleimpl_id>/evaluations
  • Exemple d'utilisation: /ScoDoc/api/moduleimpl/1/evaluations
  • Résultat: Retourne la liste des évaluations à partir de l'id d'un moduleimpl (quel que soit leur statut).
  • Exemple de résultat: moduleimpl-evaluations.json

evaluation-notes

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: evaluation_id
  • Routes: /evaluation/<int:evaluation_id>/notes
  • Exemple d'utilisation: /evaluation/1491/notes
  • Résultat: Retourne la liste des notes d'une évaluation. Les valeurs sont non normalisées (le champ note_max indique le barème), et peuvent contenir des chaînes de caractères: ABS, EXC, DEM, ...
  • Exemple de résultat: evaluation-notes.json

evaluation-notes-set

  • Méthode: POST

  • Permission: droit de saisir des notes dans cette évaluation

  • Paramètres: evaluation_id

  • Routes: /evaluation/<int:evaluation_id>/notes/set

  • Contenu: les notes à enregistrer dans l'évaluation. Les valeurs sont "brutes", entre 0 et note_max(barème de l'évaluation), EXC, ABS, SUPR...

    {
    'notes' : [ [etudid, value], ... ],
    'comment' : optional string
}

  • Résultat: json avec

    {
          "etudids_changed": [ etudids dont la note a été modifiée ],
          "etudids_with_decision": [ etudids ayant une décision de jury à vérifier ],
          "history_menu": [ html utilisé par la page de saisie ],
}

formsemestre-etat_evals

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formsemestre_id
  • Routes: /formsemestre/<int:formsemestre_id>/etat_evals
  • Exemple d'utilisation: /ScoDoc/api/formsemestre/1/etat_evals
  • Résultat: Retourne les informations sur l'état des évaluations d'un semestre donné
  • Exemple de résultat: formsemestre-etat_evals.json

API Export, Référentiel

formation-export

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formation_id, export_ids (False par défaut. Ajouter /with_ids pour le passer à True)
  • Routes:
    • /formation/<int:formation_id>/export
    • /formation/<int:formation_id>/export_with_ids
  • Exemple d'utilisation: /ScoDoc/api/formation/formation_export/1
  • Résultat: Retourne la formation, avec UE, matières, modules
  • Exemple de résultat: formation-export.json

formation-referentiel_competences

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: formation_id
  • Routes: /formation/<int:formation_id>/referentiel_competences
  • Exemple d'utilisation: api/formation/1/referentiel_competences
  • Résultat: Le référentiel de compétences d'une formation donnée (json). (pas toujours présent)
  • Exemple de résultat: formation-referentiel_competences.json

API Logos

logos

  • Méthode: GET
  • Permission: ScoSuperAdmin
  • Paramètres : Aucun
  • Route : /logos
  • Exemple d'utilisation : /ScoDoc/api/logos
  • Résultat : Liste des noms des logos définis pour le site scodoc.
  • Exemple de résultat: logos.json
  • Méthode: GET
  • Permission: ScoSuperAdmin
  • Paramètres : Aucun
  • Route: /logo/<string:nom>
  • Exemple d'utilisation : /ScoDoc/api/logo/header
  • Résultat : l'image (format png ou jpg. le format retourné dépend du format sous lequel l'image a été initialement enregistrée)
  • Exemple de résultat: logo.json

departement-logos

  • Méthode: GET

  • Permission: ScoSuperAdmin

  • Paramètres: Aucun

  • Route :

    • /departement/<string:dept>/logos
    • /departement/id/<int:departement_id>/logos

  • Exemple d'utilisation :

    • /departement/<string:dept>/logos
    • /departement/id/<int:departement_id>/logos

  • Résultat : Liste des noms des logos définis pour le département visé qui peut être désigné par son id ou par son acronyme (selon la forme de la route).

  • Exemple de résultat: departement-logos.json

  • Méthode: GET

  • Permission: ScoSuperAdmin

  • Paramètres : Aucun

  • Route :

    • /departement/<string:dept>/logo/<string:nom>
    • /departement/id/<int:departement_id>/logo/<string:nom>

  • Exemple d'utilisation:

    • /ScoDoc/api/departement/MMI/logo/header
    • /ScoDoc/api/departement/id/3/logo/header

  • Résultat : l'image (format png ou jpg)

  • Exemple de résultat: departement-logo.json

API Assiduités

Structure Assiduité

attribut type commentaire
assiduite_id int identifiant unique
etudid int identifiant unique de l'étudiant concerné par l'assiduité
moduleimpl_id int ou null identifiant unique du module concerné par l'assiduité si indiqué
date_debut string date ISO du début de la période d'assiduité
date_fin string date ISO de la fin de la période d'assiduité
etat string état de l'assiduité (present, absent, retard)
desc string ou null description de l'assiduité
user_id int ou null utilisateur ayant créé l'assiduité
est_just boolean l'assiduité est-elle justifiée
entry_date string la date d'entrée de l'assiduité

Rappel du format de date ISO : yyyy-mm-jjTHH:MM:SS Vous pouvez aussi spécifier le temps UTC en ajoutant '+HH:MM' à la fin

assiduite

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: assiduite_id
  • Routes: /assiduite/<int:assiduite_id>
  • Exemple d'utilisation: /api/assiduite/1
  • Résultat: Retourne un objet assiduité ou une erreur si l'id n'est pas connu
  • Exemple de résultat: assiduite.json

assiduites[-query]

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid
  • Query string:
    • etat ('present','retard','absent)
    • moduleimpl_id (X : id du moduleimpl concerné)
    • date_debut (X : date format iso)
    • date_fin (X : date format iso)
    • formsemestre_id (X : id du formsemestre)
    • est_just (v,t,f,vrai,faux,true,false)
    • user_id (X : id de l'utilisateur)
  • Routes:
    • /assiduites/<int:etudid>
    • /assiduites/<int:etudid>/query?
  • Exemple d'utilisation:
    • /api/assiduites/1
    • /api/assiduites/1/query?etat=retard
    • /api/assiduites/1/query?moduleimpl_id=1
  • Résultat: Liste de toutes les objets assiduité qui correspondent aux critères sélectionnés
  • Exemple de résultat: assiduites.json

assiduites-count[-query]

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid
  • Query string:
    • etat ('present','retard','absent)
    • moduleimpl_id (X : id du moduleimpl concerné)
    • date_debut (X : date format iso)
    • date_fin (X : date format iso)
    • formsemestre_id (X : id du formsemestre)
    • est_just (v,t,f,vrai,faux,true,false)
    • user_id (X : id de l'utilisateur)
    • metric ('compte', 'demi', 'journee', 'heure')
  • Routes:
    • /assiduites/<int:etudid>/count
    • /assiduites/<int:etudid>/count/query?
  • Exemple d'utilisation:
    • /api/assiduites/1
    • /api/assiduites/1/count/query?etat=retard
    • /api/assiduites/1/count/query?moduleimpl_id=1
    • /api/assiduites/1/count/query?etat=present,retard&metric=compte,heure
  • Résultat: les métriques obtenu à partir des assiduitées correspondant aux critères sélectionnés
  • Exemple de résultat: assiduites-count.json

assiduites-formsemestre[-query]

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid
  • Query string:
    • etat ('present','retard','absent)
    • moduleimpl_id (X : id du moduleimpl concerné)
    • date_debut (X : date format iso)
    • date_fin (X : date format iso)
    • est_just (v,t,f,vrai,faux,true,false)
    • user_id (X : id de l'utilisateur)
  • Routes:
    • /assiduites/formsemestre/<int:formsemestre_id>
    • /assiduites/formsemestre/<int:formsemestre_id>/query?
  • Exemple d'utilisation:
    • /api/assiduites/formsemestre/1
    • /api/assiduites/formsemestre/1/query?etat=retard
    • /api/assiduites/formsemestre/1/query?moduleimpl=1
  • Résultat: Liste de toutes les objets assiduité des étudiants du formsemestre qui correspondent aux critères sélectionnés
  • Exemple de résultat: assiduites_formsemestre.json

assiduites-formsemestre-count[-query]

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid
  • Query string:
    • etat ('present','retard','absent)
    • moduleimpl_id (X : id du moduleimpl concerné)
    • date_debut (X : date format iso)
    • date_fin (X : date format iso)
    • est_just (v,t,f,vrai,faux,true,false)
    • user_id (X : id de l'utilisateur)
  • Routes:
    • /assiduites/formsemestre/<int:formsemestre_id>/count
    • /assiduites/formsemestre/<int:formsemestre_id>/count/query?
  • Exemple d'utilisation:
    • /api/assiduites/formsemestre/1/count
    • /api/assiduites/formsemestre/1/count/query?etat=retard
    • /api/assiduites/formsemestre/1/count/query?moduleimpl=1&metric=demi,journee
  • Résultat: les métriques obtenu à partir des assiduitées de tous les étudiants du formsemestre correspondant aux critères sélectionnés
  • Exemple de résultat: assiduites_formsemestre-count.json

assiduites-group[-query]

  • Méthode: GET
  • Permission: ScoView
  • Query string:
    • etudids Obligatoire (liste des etudids sous la forme x,y,z,...)
    • etat ('present','retard','absent)
    • moduleimpl_id (X : id du moduleimpl concerné)
    • date_debut (X : date format iso)
    • date_fin (X : date format iso)
    • est_just (v,t,f,vrai,faux,true,false)
    • user_id (X : id de l'utilisateur)
  • Routes:
    • /assiduites/group/query?etudids=
  • Exemple d'utilisation:
    • /assiduites/group/query?etudids=1,2,3
    • /assiduites/group/query?etudids=1,2,3&etat=retard
    • /assiduites/group/query?etudids=1,2,3&moduleimpl=1
  • Résultat: 
    {
  etudid1 : [{assiduité...}],
  etudid2 : [{assiduité...}],
  etudid3 : [{assiduité...}],
}

assiduites-create

  • Méthode: POST
  • Permission: ScoAssiduiteChange
  • Data:
[
  { 
    "etudid":<int>,

    "date_debut": <string>,
    "date_fin": <string>,
    "etat": <string>,
    "moduleimpl_id"?: <int>,
    "desc"?:<string>,
  },
  ...
]
  • Routes:
    • /assiduites/create
  • Exemple d'utilisation: /api/assiduites/create

[{date_debut: "2022-10-27T08:00",date_fin: "2022-10-27T10:00",etat: "absent",etudid:1}]

  • Résultat: Retourne un objet en deux partie (errors et success) contenant le retour de chaque objet donné dans la requête post.

assiduite-create

  • Méthode: POST
  • Permission: ScoAssiduiteChange
  • Paramètres: etudid
  • Data:
[
  {
    "date_debut": <string>,
    "date_fin": <string>,
    "etat": <string>,
    "moduleimpl_id"?: <int>,
    "desc"?:<string>
  },
  ...
]
  • Routes:
    • /assiduite/<int:etudid>/create
  • Exemple d'utilisation: /api/assiduite/1/create

[{date_debut: "2022-10-27T08:00",date_fin: "2022-10-27T10:00",etat: "absent"}]

  • Résultat: Retourne un objet en deux partie (errors et success) contenant le retour de chaque objet donné dans la requête post.
  • Exemple de résultat: assiduite_create.json

assiduite-edit

  • Méthode: POST
  • Permission: ScoAssiduiteChange
  • Paramètres: assiduite_id
  • Data:
{
    "etat": <string>,
    "moduleimpl_id": <int>,
    "desc" : <string>,
}
  • Routes: /assiduite/<int:assiduite_id>/edit
  • Exemple d'utilisation: /api/assiduite/1/edit

{etat: "absent"}

  • Résultat: Modifie l'assiduité désignée. Renvoie une erreur si la modification rend incompatible la plage de l'assiduité par rapport aux autres assiduités du même étudiant
  • Exemple de résultat: assiduite_edit.json

assiduites-edit

  • Méthode: POST
  • Permission: ScoAssiduiteChange
  • Data:
[
  {
    "etudid":<int>
    "etat"?: <string>,
    "moduleimpl_id"?: <int>
    "desc"?:<string>
  },
  ...
]
  • Routes:
    • /assiduites/edit
  • Exemple d'utilisation: /api/assiduites/edit

[{etat: "absent",assiduite_id:1},{etat: "retard",moduleimpl_id:12,assiduite_id:2}]

  • Résultat: Retourne un objet en deux partie (errors et success) contenant le retour de chaque objet donné dans la requête post.

assiduite-delete

  • Méthode: POST
  • Permission: ScoAssiduiteChange
  • Data:
[
  <int:assiduite_id>,
  ...
]
  • Routes:
    • /assiduite/delete
  • Exemple d'utilisation: /api/assiduite/delete

[2,3,5,7]

  • Résultat: Retourne un objet en deux partie (errors et success) contenant le retour de chaque objet donné dans la requête post.
  • Exemple de résultat: assiduite_delete.json

Structure Justificatif

attribut type commentaire
justif_id int identifiant unique
etudid int identifiant unique de l'étudiant concerné par le justificatif
date_debut string date ISO du début de la période du justificatif
date_fin string date ISO de la fin de la période du justificatif
etat string état du justificatif ( attente, valide, non_valide, modifie)
raison string ou null explication du justificatif si présente
fichier string identifiant de l'archivage des fichiers
entry_date string date ISO de l'entrée du justificatif

justificatif

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: justif_id
  • Routes: /justificatif/<int:justif_id>
  • Exemple d'utilisation: /api/justificatif/1
  • Résultat: Retourne un objet justificatif ou une erreur si l'id n'est pas connu
  • Exemple de résultat: justificatif.json

justificatifs[-query]

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: etudid
  • Query string:
    • etat ( attente, valide, non_valide, modifie)
    • date_debut (X : date format iso)
    • date_fin (X : date format iso)
  • Routes:
    • /justificatifs/<int:etudid>
    • /justificatifs/<int:etudid>/query?etat=VALIDE
  • Exemple d'utilisation:
    • /api/justificatifs/1
    • /api/justificatifs/1/query?etat=modifie
    • /api/justificatifs/1/query?date_debut=2022-10-27T08:00
  • Résultat: Liste de toutes les objets justificatifs qui correspondent aux critères sélectionnés
  • Exemple de résultat: justificatifs.json

justificatif-create

  • Méthode: POST
  • Permission: ScoJustifChange
  • Paramètres: etudid
  • Data:
[
  {
    "etat": <string>,
    "date_debut": <string>,
    "date_fin": <string>,
    "raison"?: <string>,
  },
  ...
]

Un fichier justificatif peut être importé dans scodoc après avoir créer l'objet justificatif voir importer un justificatif

  • Routes: /justificatif/<int:etudid>/create
  • Exemple d'utilisation: /api/justificatif/1/create
[
  {
    "etat": "attente",
    "date_debut": "2022-10-27T08:00",
    "date_fin": "2022-10-27T12:00",
    "raison": "Opération médicale",
  }
]
  • Résultat: Retourne un objet en deux partie (errors et success) contenant le retour de chaque objet donné dans la requête post.
  • Exemple de résultat: justificatif-create.json

justificatif-edit

  • Méthode: POST
  • Permission: ScoJustifChange
  • Paramètres: justif_id
  • Data:
{
    "etat": <string>,
    "raison": <string>,
    "date_debut": <string>,
    "date_fin": <string>,
}
  • Routes: /justificatif/<int:justif_id>/edit
  • Exemple d'utilisation: /api/justificatif/1/edit

{etat: "valide"}

justificatif-delete

  • Méthode: POST
  • Permission: ScoJustifChange
  • Paramètres: etudid
  • Data:
[
  <int:justif_id>,
  ...
]
  • Routes: /justificatif/delete
  • Exemple d'utilisation: /api/justificatif/delete
[
  2,3,5,7
]
  • Résultat: Retourne un objet en deux partie (errors et success) contenant le retour de chaque objet donné dans la requête post.
  • Exemple de résultat: justificatif-delete.json

justificatif-import

  • Méthode: POST
  • Permission: ScoJustifChange
  • Paramètres: justif_id

Procédure d'importation de fichier : importer un justificatif

  • Routes: /justificatif/<int:justif_id>/import

  • Résultat: Le nom du fichier archivé (nom coté serveur)

  • Exemple de résultat: justificatif-import.json

justificatif-export

  • Méthode: POST
  • Permission: ScoJustifChange
  • Paramètres:
    • justif_id
    • filename

Procédure de téléchargement de fichier : télécharger un justificatif

  • Routes: /justificatif/<int:justif_id>/export/<str:filename>

  • Résultat: le fichier (téléchargement direct / renvoie octets)

  • Exemple de résultat: justificatif-export.json

justificatif-remove

  • Méthode: POST
  • Permission: ScoJustifChange
  • Paramètres: justif_id

Procédure de suppression de fichier : supprimer un justificatif

  • Routes: /justificatif/<int:justif_id>/remove

  • Résultat: {response:"removed"} ou une erreur

  • Exemple de résultat: justificatif-remove.json

justificatif-list

  • Méthode: GET

  • Permission: ScoView / ScoJustifView

    • Si ScoView : retourne uniquement les fichiers fourni par le même utilisateur
    • Si ScoJustifView : retourne tous les fichiers

  • Paramètres: justif_id

  • Routes: /justificatif/<int:justif_id>/list

  • Exemple d'utilisation: /api/justificatif/1/list

  • Résultat:

      {
    "filenames" : [
      <str>,
      ...
    ],

    "total": <int>
  }
    • Le total indique le nombre total de fichiers (visibles ou non)

  • Exemple de résultat: justificatif-list.json

justificatif-justifies

  • Méthode: GET
  • Permission: ScoView
  • Paramètres: justif_id
  • Routes: /justificatif/<int:justif_id>/justifies
  • Exemple d'utilisation: /api/justificatif/1/justifies
  • Résultat: Retourne la liste des assiduite_id qui sont justifiés par le justificatif ou une erreur si l'id n'est pas connu
  • Exemple de résultat: justificatif-justifies.json

En savoir plus

Voir exemples d'utilisation de l'API en Python, dans tests/api/.

Fonctions de l'API ScoDoc 7 portées en ScoDoc 9

Février 2023: L'ancienne API ScoDoc 7 n'est plus documentée et plus disponible.

Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les fonctions suivantes sont disponibles avec le mécanisme d'authentification basique de ScoDoc 7. Elles sont considérées comme obsolètes ("deprecated") et disparaitront en juillet 2022.

Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès.

  • Absences/XMLgetBilletsEtud (deviendra api/absences/billets/etud/ etudid>)
  • Absences/AddBilletAbsence (deviendra api/absences/billet/add)
  • Absences/XMLgetAbsEtud (deviendra api/absences/ etudid>, en json)
  • Notes/evaluation_listenotes (non existante en ScoDoc9, trop complexe)
  • Notes/formsemestre_id (deviendra api/formsemestre)
  • Notes/formsemestre_bulletinetud (deviendra api/etud/<etudid>/bul/<formsemestre_id>)
  • Notes/XMLgetFormsemestres (non existante en ScoDoc9, redondant avec api/formsemestre ?)
  • etud_info ou XMLgetEtudInfos ou Absences/XMLgetEtudInfos ou Notes/XMLgetEtudInfos (deviendra /api/etud/<etudid>)
  • groups_view (deviendra groups)

Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est à dire https://votre.site.fr/ScoDoc/<dept>/Scolarite/, et répondent en GET et en POST.

Note:

  • Absences/listeBillets est un formulaire et ne fait pas partie de l'API.

!!! note "Voir aussi"

- [Guide configuration et ligne de commande](GuideConfig.md)
- [Guide administrateur ScoDoc](GuideAdminSys.md)
- [FAQ](FAQ.md)
- [Contacts](Contact.md)