Modèle de données

Exemple d'une interface présentant des données pouvant être consommées par AppScho

Cette page tente de décrire de façon succinte les données minimales nécessaires au bon fonctionnement d'AppScho. Cette liste représente un sous-ensemble des données qui peuvent être fournie par l'ERP d'un établissement, et peut donc être complétée en fonction du besoin.

Le format recommandé pour ces échanges est le JSON à travers HTTP. Pour une interface aussi "simple", nous préférerons une interface REST à un modèle complexe RPC tel que SOAP.

Veuillez noter que pour chaque élément renvoyé par vos systèmes d'information, il est nécessaire de fournir un ID unique afin de permettre à AppScho d'identifier correctement les modifications.

Si cet ID est manquant ou n'est pas unique, vous pourrez rencontrer des problèmes liés aux notifications présentées à vos utilisateurs.

Authentification utilisateurs

Deux possibilités s'offrent à nous ici :

  • Utiliser un système d'authentification géré par l'outil établissement. Ici, l'utilisateur concerné est intrisèquement identifié par le token d'authentification généré et fourni par l'outil établissement.

  • Authentifier l'utilisateur côté AppScho et faire en sorte que l'outil établissement fasse confiance aux requêtes faites par AppScho. Dans ce cas, les requêtes à l'API contiendrait l'identifiant de l'utilisateur concerné en paramètre.

Vous pouvez retrouver des détails sur certaines méthodes d'authentification supportées dans la section dédiée de cette documentation.

Informations utilisateurs

Une fois l'utilisateur connecté, nous avons la possibilité de récupérer des informations sur sa personne et son profil au sein de l'établissement. Les données essentielles étant les suivantes :

  • le prénom

  • le nom

D'autres données annexes et / ou composites peuvent être fournies dans cette réponse, par exemple :

  • la photo

  • le programme d'inscription

  • la promotion

  • le profil de l'utilisateur (pouvant conditionner l'affichage de l'application - à définir avec vos partenaires projets AppScho)

    • Valeurs possibles :

      • student

      • teacher

      • staff

      • alumni

  • une liste de groupes desquels l'étudiant fait partie (cette liste de groupes est utilisée par les systèmes de push d'iOS et Android, de ce fait, ils doivent rester des ID simple (lettre, chiffres, et tirets)

{
  "firstname": "Antoine",
  "lastname": "POPINEAU",
  "picture": "https://server.school.com/xxx.png",
  "program": "Master in Management",
  "promotion": "2019",
  "profile" : "student",
  "groups": [
    "master",
    "master-management",
    "promotion-2019"
  ]
}

Audiences

En plus des groupes renvoyés à travers les informations utilisateurs (voir ci-dessus), il est nécessaire de nous mettre à disposition la liste intégrale des groupes disponibles (afin de les afficher aux administrateurs de la plateforme My AppScho. Ces groupes doivent posséder un nom commun ainsi qu'un ID (qui est celui renvoyé pour l'utilisateur) :

[
  {
    "id": "master",
    "label": "Etudiants en master"
  },
  {
    "id": "master-management",
    "label": "Etudiants du master en management"
  }
]

Notes

Ici, nous devons récupérer une liste d'examens, possédant les attributs propres à cet examen, par exemple :

  • le nom de la matière

  • la date de l'examen

  • la note obtenue

  • le nombre de crédits ECTS en jeu

Ces examens peuvent être organisés en une hiérarchie permettant le classement en années, semestres, groupes, etc. Nous recommandons de limiter au possible la profondeur hiérarchique afin d'optimiser l'usage sur mobile (par exemple Année > Semestre > Matière > Examen).

[
  {
    "uid": "Y2018",
    "title": "2018-2019",
    "children": [
      {
        "uid": "Y2018S1",
        "title": "Semester 1"
        "grade": "18.3"
        "children": [
          {
            "uid": "Y2018S1-1234",
            "title": "Management 101",
            "grade": "16",
            "comment": "Very good job!"
          }
        ]
      },
      {
        "uid": "Y2018S2",
        "title": "Semester 2"
        "children": []
      }
    ]
  }
]

Emploi du temps

L'emploi du temps une simple liste d'événements comprenant, au minimum, les informations suivantes :

  • un ID unique pour l'événement

  • le nom de l'événementla date et heure de début la date et heure de fin

L'ID unique à renvoyer avec l'événement nous est utile afin de déterminer si un événement a été modifié (nous comparons les champs pour les événements possédant le même ID). Il est donc important que cet ID ne change pas lorsqu'un événement est modifié.

Le format pour les dates renvoyées importe peu tant que celui-ci est précis (avec fuseau horaire).

Chaque événement peut aussi, si disponible, inclure les informations suivantes :

  • le nom de la salle où se situe l'événement

  • le nom du professeur

  • une description plus complète de l'événement

  • un lien vers une plateforme LMS

  • un lien de visioconférence

  • la couleur hexadécimale que doit prendre l'évènement dans le planning

[
  {
    "uid": "2016-1234567890",
    "title": "Market strategy",
    "start": "2017-02-12T09:30:00+0200",
    "end": "2017-02-12T11:30:00+0200",
    "location": "Building B - Room 302",
    "teacher": "Antoine POPINEAU",
    "description": "MS course",
    "platform_link": "https://example.link.com"
    "visio_link": "https://example.visio.com/l/meetup-join/123456"
    "color": "0000FF"
  }
]

Alertes Personnalisées

Nous récupérons ici une liste d'alertes. Chaque alerte possède un ID unique, un titre ainsi qu'une description. Elles seront affichées directement sur le tableau de bord de l'application.

[
  {
    "uid": "123456789",
    "title": "Convention de Stage",
    "desc": "Merci de compléter et signer votre convention de stage avant le 01/01/2020"
  }
]

Absences

Une liste d'absences comprenant, au minimum, les données suivantes :

  • le nom du cours concerné

  • la date et l'heure de l'absence

  • un booléan indiquant si l'absence est justifiée ou non

Optionnellement, une absence peut contenir les attributs suivantes :

  • la justification de l'absence

[
  {
    "class": "Market strategy",
    "start": "2017-02-13T14:00:00+0200",
    "end": "2017-02-13T15:00:00+0200",
    "justified": true,
    "justification": "L'étudiant a fourni son certificat médical.",
    "comment": "Etudiant ne s'est pas présenté en salle de cours.",
    "teacher": "Antoine POPINEAU"
  }
]

Annuaire

L'annuaire peut avoir une ou deux interfaces différentes.

L'interface indispensable concerne la recherche. Un paramètre fournit la chaîne de caractères recherchée, encodée pour être contenue dans une URL (et donc pouvant contenir des espaces). Par exemple /directory/search?term=antoine%20popineau. Cet endpoint doit renvoyé une liste d'entités répondant au critère de recherche, par exemple :

[
  {
    "id": 18745,
    "firstname": "Antoine",
    "lastname": "POPINEAU",
    "type": "teacher",
    "email": "antoine.popineau@school.edu",
    "phone": "+33123456789",
    "picture": "https://school.edu/pictures/18745.jpg"
  }
]

Documents

La liste de documents doit être organisée de manière similaire aux notes, à savoir une hiérarchie de descripteurs de documents, qui sera répliquée dans l'application de l'utilisateur.

Chaque niveau peut contenir des enfants (dans ce cas, le niveau en question est un dossier). Si un noeud de l'arbre ne contient aucun enfant, il s'agit un document et doit donc contenir des information supplémentaires décrivant le document en question. Un point important est à noter : le document doit être téléchargeable à travers HTTPS directement par le terminal mobile, cela signifie une de deux choses : celui-ci est accessible publiquement, sans authentification, ou être authentifié directement à travers des paramètres fournis dans l'URL du document.

[
  {
    "uid": "26f88685-b775-446d-a2e7-81cd2f8160d2",
    "title": "Attestations de scolarité",
    "children": [
      {
        "uid": "8fd8cbae-dcf3-46f6-9311-f4d731e0b6c5",
        "title": "Attestation de scolarité 2020",
        "url": "https://example.com/files/fa39f0ab-53bd-4f81-b108-61b585b0b6b.pdf?token=c5af0d6d-14da-4865-b59d-25a84a0497c1",
        "filename": "Attestation de scolarité 2020.pdf"
      },
      {
        "uid": "07109524-6432-4797-b5cd-812b111def7c",
        "title": "Attestation de scolarité 2019",
        "url": "https://example.com/files/7230eaca-1062-4987-8945-c173640b9c76.pdf?token=c5af0d6d-14da-4865-b59d-25a84a0497c1",
        "filename": "Attestation de scolarité 2019.pdf"
      }
    ]
  }
]

Il est possible d'indiquer, à travers un attribut spécifique (ici filename) le nom que doit avoir le fichier une fois téléchargé, dans la mesure du possible.

Paiements

La fonctionnalité Paiements affiche deux types d'informations :

  • une liste de "situations" permettant d'afficher au moins un solde

  • une liste de paiements et leurs états respectifs

Ces informations peuvent être renvoyées dans un seul appel ou deux appels différents, en fonction de ce qui est plus pratique côté établissement.

Un élément de situation doit contenir les éléments suivants :

  • ID unique

  • Titre

  • Description

  • Solde (positif ou négatif)

Un élément de paiement doit contenir les éléments suivants :

  • ID unique

  • Titre

  • Description

  • Montant

  • Booléen indiquant si le paiement a été réalisé

  • Booléen indiquant si le paiement a échoué

  • Date de paiement

{
  "balances": [
    {
      "uid": "956dc15c-ada5-4424-80c4-0efc51c8caaa",
      "title": "Année 2019/2020",
      "description": "Frais de scolarité pour l'année 2019/2020",
      "balance": -200.5
    }
  ],
  "payments": [
    {
      "uid": "956dc15c-ada5-4424-80c4-0efc51c8caaa",
      "title": "Paiement mensuel - Décembre 2020",
      "amount": 100.0,
      "paid": true,
      "failed": false,
      "paid_on": "2020-12-01T00:00:00+01:00"
    }
  ]
}

Suivi administratif

Le suivi administratif présente une liste d'étapes que l'étudiant doit remplir (généralement, des document à renvoyer et qui doivent être vérifiés et affiche le status de ceux-ci ainsi que des éléments explicatifs (PDF et/ou vidéo) sur le processus.

Nous pouvons récupérer ces informations grâce à un modèle similaire à celui-ci : 

{
  "name": "Inscription à la sécurité sociale",
  "deadline": "2021-09-10T00:00:00+02:00",
  "sent": true,
  "sent_on": "2021-08-15T15:00:00+02:00",
  "approved": true,
  "rejected": false,
  "approved_on": "2021-08-20T00:00:00+02:00",
  "comment": "Document validé.",
  "pdf": "https://appscho.com/documents/securite-sociale.pdf",
  "video": "https://appscho.com/videos/securite-sociale"
}

Prochains passage des transports en commun

Nous tentons généralement de récupérer ces informations directement depuis des API temps réel fournies par les sociétés de transports en commun locales à vos établissements, si celles-ci existent. Nous pouvons également, si nécessaire, utiliser des API que vous auriez développé afin de récupérer ces mmes informations.

Les données à renvoyer doivent prendre la forme d'une liste de passages à venir pour un ou plusieurs arrts autour de votre campus, contenant les informations ci-dessous :

  • Nom de la ligne

  • Nom de l'arrt

  • Direction

  • Horaire de passage (complet avec date, heure, et fuseau horaire)

  • Couleur de fond du logo de la ligne

  • Couleur du texte du logo de la ligne

  • Coordonnées GPS de l'arrt

[
  {
    "line": "42",
    "stop": "Soleil Sud",
    "direction": "Centre commercial La Belle Affaire",
    "time": "2021-11-03T15:01:13+01:00",
    "coordinates": {
      "latitude": "48.8619947",
      "longitude": "2.34743"
    },
    "colors": {
      "background": "FF0000",
      "text": "00FF00"
    }
  },
  {}
]

Menus des restaurants

Cet exemple de modèle de données peut etre ignoré si vous souhaitez qu'AppScho intègre les restaurants et menus publiés dans l'Open Data du CROUS.

Si, en revanche, vous désirez mettre à disposition vos propre données, ce modèle doit etre respecté.

La récupération des menus des restaurants se déroule en trois étapes :

  1. La liste des campus / CROUS

  2. La liste des restaurants par CROUS

  3. Le menu pour chaque restaurant

Liste des CROUS

Cette étape sert à présenter l'utilisateur avec un menu de sélection pour passer d'un "groupe" de restaurant à l'autre. Ces groupes représentent généralement des campus ou des régions.[

[
  {
    "id": "poitiers",
    "name": "CROUS de Poitiers"
  },
  {
    "id": "toulouse",
    "name": "CROUS de Toulouse"
  }
]

Chaque ID ici sera utilisé dans les requetes suivantes afin d'interroger la liste des restaurants par groupe.

Liste des restaurants par groupe

Cet appel doit retourner la liste des restaurant pour un groupe donné (la manière de transmettre l'ID du groupe dépendra de l'implémentation et est laissé à la discrétion de l'éditeur).

Chaque restaurant doit comporter les éléments suivants :

  1. Un ID unique identifiant le restaurant

  2. Un nom

  3. Une photo (optionnel)

  4. Une adresse (optionnel)

  5. Des coordonées GPS (optionnel)

  6. Un commentaire (optionnel)

  7. Une indication de l'état actuel d'ouverture du restaurant

  8. L'état d'ouverture du restaurant par jour de la semaine et par tranche horaire (de lundi à dimanche, pour le matin, midi et le soir)

[
    {
        "id": "r806",
        "name": "Cafet' Arum",
        "kind": "Cafétéria",
        "picture": "https://www.crous-toulouse.fr//wp-content/uploads/sites/36/2017/03/Arum-resto.jpg",
        "contact": "5, allée Antonio Machado 31058 Toulouse - Téléphone -  : 05 61 12 55 78 - E-mail -  : restaurant.mirail@crous-toulouse.fr",
        "coordinates": {
            "latitude": "43.57667",
            "longitude": "1.40112"
        },
        "comment": "Sur le campus UT2J. Formules sandwichs, paninis, salades, petit déjeuners, boissons, vente à emporter ...\nIci, point de retrait du Crous and go' en Click and Collect : https://crousandgo.crous-toulouse.fr/arum",
        "closed": false,
        "schedule": [
            {
                "morning": true,
                "noon": true,
                "evening": true
            },
            {
                "morning": true,
                "noon": true,
                "evening": false
            },
            {
                "morning": true,
                "noon": true,
                "evening": false
            },
            {
                "morning": true,
                "noon": true,
                "evening": false
            },
            {
                "morning": true,
                "noon": true,
                "evening": false
            },
            {
                "morning": false,
                "noon": false,
                "evening": false
            },
            {
                "morning": false,
                "noon": false,
                "evening": false
            }
        ]
    }
]

Menu pour un restaurant

Pour un restaurant donné (identifié par son groupe et son ID unique), son menu doit pouvoir etre interrogé, retournant, pour chaque jour, pour différentes périodes, des sections (par exemple, entrée, plat et dessert) contenant des éléments.

[
  {
    "date": "2022-06-06 00:00:00 +0000",
    "periods": [
      {
        "period": "midi",
        "section": [
          {
            "title": "Plats du jour",
            "items": [
              "RU fermé lundi de Pentecôte"
            ]
          },
          {
            "title": "Végétarien",
            "items": [
              "menu non communiqué"
            ]
          },
          {
            "title": "Grillade",
            "items": [
              "menu non communiqué"
            ]
          },
          {
            "title": "Pizzas / Pâtes",
            "items": [
              "menu non communiqué"
            ]
          }
        ]
      }
    ]
  },
  {
    "date": "2022-06-07 00:00:00 +0000",
    "periods": [
      {
        "period": "midi",
        "section": [
          {
            "title": "Plats du jour",
            "items": [
              "cabillaud crumble",
              "chou fleur persillé",
              "semoule"
            ]
          },
          {
            "title": "Végétarien",
            "items": [
              "galette tomate & mozzarella",
              "avec accompagnement"
            ]
          },
          {
            "title": "Grillade",
            "items": [
              "cuisse de poulet",
              "légumes & frites"
            ]
          },
          {
            "title": "Pizzas / Pâtes",
            "items": [
              "menu non communiqué"
            ]
          }
        ]
      }
    ]
  }
]
PreviousMoodleNextAdresses IP

Last updated